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下 人 一、 人“ 
月 二 


为 什么 要 写 这 本 习 





目 第 1 版 友 行 以 来 ， 笔 者 很 欣慰 得 到 了 广大 读者 的 认可 。 本 书 一 直人 致力 于 说 明 开 发 Nginx 
模块 的 必 备 知识 ， 然 而 由 于 Nginx 功 能 繁多 且 性 能 强大 ， 以 致 必须 要 了 解 的 基本 技能 也 很 庞 
杂 ， 而 第 1 版 成 书 匆 忙 ， 缺 失 了 几 个 进 阶 的 技巧 描述 〈 例 如 如 何 使 用 变量 、slab 共 宇内 存 
等 ) ， 因 此 决定 在 第 1 版 的 基础 上 进 一 








事实 上 ， 我 们 总 能 在 nginx.conf 邵 置 文件 中 看 到 各 种 带 厦 $ 符 号 的 变量 ， 只 要 修改 带 厦 变 
量 的 这 一 行 行 配置 ， 就 可 以 不 用 编译 、 部 闭 而 使 得 Nginx 有 具备 新 功能 ， 这 些 文 持 变量 的 Nginx 
模块 提供 了 极为 灵活 的 功能 ， 第 2 版 通过 新 增 的 第 15 章 详细 介绍 了 如 何在 模块 中 支持 HTTP 变 
量 ， 包 括 如 何在 代码 中 使 用 其 他 Nginx 模 块 提 供 的 变量 ， 以 及 如 何 定义 新 的 变量 供 nginx.conf 
和 其 他 第 三 方 模块 使 用 等 。 第 16 章 介绍 了 slab 共 享 内 存 ， 这 是 一 套 适 用 于 小 块 内 存 快速 分 配 
释放 的 内 存 窟 理 方式 ， 它 非常 高 效 ， 分 配 与 释放 速度 都 是 以 纳 秒 计算 的 ， 常 用 于 多 个 worker 
进程 之 间 的 通信 ， 这 比 第 14 间 介绍 的 原始 的 共有 至 内 存 通 信和 方式 要 先进 很 多 。 第 16 间 不仅 详细 
介绍 了 它 的 实现 方式 ， 也 探讨 了 它 的 优 缺 点 ， 比 如 ， 如 果 模 块 间 要 共享 的 单个 对 象 常常 要 消 
耗 数 KB 的 空间 ， 这 时 就 需要 修改 它 的 实现 《例如 增 大 定义 的 slab 页 大 小 ) ， 以 避免 内 存 的 滔 


机 





























Nginx 内 存 池 在 第 1 版 中 只 是 简单 市 过 ， 第 2 版 中 新 增 了 8.7 市 介绍 了 内 存 池 的 实现 细节 ， 
以 帮助 读者 用 好 最 基础 的 内 存 池 功能 


此 外 ， 很 多 读者 反馈 需要 结合 TCP 来 谈 谈 Nginx， 因 此 在 9.10 节 中 笔者 试图 在 不 陷入 Linux 
内 核 细 节 的 情况 下 ， 简 要 介绍 了 TCP 以 清晰 了 解 Nginx 的 事件 框架 ， 了 解 Nginx 的 高 并 发 能 
J 
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这 一 版 新 增 的 第 15 章 的 样 例 代 码 可 以 从 http://nginx.taohui.org.cn 站 点 上 下 载 。 





导 笔 者 工作 繁忙 ， 以 致 第 2 版 拖 稿 严重 ， 该 者 的 邮件 也 无 法 及 时 回复 ， 非 党 抱歉 。 从 这 
版 开始 会 把 曾经 的 回复 整理 后 放 在 网 站 上 ， 想 必 这 比 回复 邮件 要 更 有 效率 些 。 





读者 对 象 


本 书 适合 以 下 读者 阅读 。 

` 对 Nginx 及 如 何 将 它 搭 建成 一 个 高 性 能 的 Web 服 务 器 感 兴趣 的 读者 。 

希望 通过 开发 特定 的 HTTP 模 块 实现 高 性 能 Web 服 务 器 的 读者 。 
希望 了 解 Nginx 的 架构 设计 ， 学 习 其 怎样 充分 使 用 服务 器 上 的 硬件 资源 的 读者 。 
了 解 如 何 快速 定位 、 修 复 Nginx 中 深层 次 Bug 的 读者 。 


“ 希望 利用 Nginx 提 供 的 框架 ， 设 计 出 任何 基于 TCP 的 、 无 阻塞 的 、 易 于 扩展 的 服务 器 
的 读者 。 


背景 知识 

如 果 仅 希望 了 解 怎样 使 用 已 有 的 Nginx 功 能 搭建 服务 器 ， 那 么 阅读 本 书 不 需要 什么 先决 
条 件 。 但 如 果 希 望 通过 阅读 本 书 的 第 二 、 第 三 两 部 0 & 构 设计 
技巧 时 ， 则 必须 了 解 C 语 言 的 基本 语法 。 在 阅读 本 书 第 三 部 分 时 ， 需 要 读者 对 TCP 有 一 个 基 
本 的 了 解 ， 同 时 对 Linux 操 作 系 统 也 应 该 有 简单 的 了 解 。 





如 何 阅 读本 书 


ee | ste Pn step” 式 ew en 5 中 Lr eo 








者 的 时 间 ， 然 而 ， 由 于 3 个 主要 写作 目的 想 解决 的 问题 都 不 是 那么 简单 ， 所 以 这 本 书 只 能 做 
一 个 折 中 的 处 理 。 


Ew 


第 一 部 分 的 前 两 章 中 ， 将 只 探讨 如 何 使 用 Nginx 这 一 个 问题 。 阅 读 这 一 部 分 的 读者 不 

需要 了 解 C 语 言 ， 束 可 以 学 习 如 何 部 署 Nginx， 学 习 如 何 问 其 中 添加 各 种 官方 、 第 三 方 的 功能 
模块 ， 如 何 通 过 修改 配置 文件 来 更 改 Nginx 及 各 模块 的 功能 ， 如 何 修 改 Linux 操 作 系 统 上 的 参 
数 来 优化 服务 器 性 能 ， 最 终 同 用 户 提 供 企业 级 的 Web 服 务 融 。 这 一 部 分 介绍 配置 项 的 方式 ， 

更 偏重 于 领 着 对 Nginx 还 比较 陌生 的 读者 熟悉 它 ， 通 过 了 解 几 个 基本 Nginx 模 块 的 配置 修改 方 
式 ， 进 而 使 读者 可 以 通过 但 询 官网 、 第 三 方 网 站 来 了 解 如 何 使 用 所 有 Nginx 模 块 的 用 法 。 








在 第 二 部 分 的 第 3 章 ~ 第 7 章 中 ， 都 是 以 例子 来 介绍 HTTP 模 块 的 开发 方式 的 ， 这 里 有 些 接 
近 于 “step by step” 的 学 习 方 式 ， 我 在 写作 这 一 部 分 时 ， 会 通过 循序 渐进 的 方式 使 读者 能 够 快 
速 上 手 ， 同 时 会 穿插 着 介绍 其 常见 用 法 的 基本 原理 。 


在 第 三 部 分 ， 将 开始 介绍 Nginx 的 完整 框架 ， 阅 读 到 这 里 将 会 了 解 第 二 部 分 中 HTTP 模 块 
为 何以 此 种 方式 开发 ， 同 时 将 可 以 轻易 地 开发 Nginx 模 块 。 这 一 部 分 并 不 仅仅 满足 于 阐述 
Nginx 架 构 ， 而 是 会 探讨 其 为 何如 此 设计 ， 只 有 这 样 才 能 扫 开 HTTP 框 架 、 邮 件 代理 框架 ， 实 
现 一 种 新 的 业务 框架 、 一 种 新 的 模块 类 型 。 





对 于 Nginx 的 使 用 还 不 熟悉 的 读者 应 当 从 第 1 章 开 始 学 习 ， 前 两 草 将 帮助 你 快速 了 解 
Nginx。 


使 用 过 Nginx， 但 对 如 何 开 发 Nginx 的 HTTP 模 块 不 太 了 解 的 读者 可 以 直接 从 第 3 章 开始 学 
习 ， 在 这 一 章 阅 读 完 后 ， 即 可 编写 一 个 功能 大 致 完整 的 HTTP 模 块 。 然 而 ， 编 写 企业 级 的 模 
块 必 须 阅读 完 第 4 章 才能 做 到 ， 这 一 章 将 会 介绍 编写 产品 线 上 服务 器 程序 时 必 备 的 3 个 手段 。 
第 5 章 举 例 说 明了 两 种 编写 复杂 HTTP 模 块 的 方式 ， 在 第 三 部 分 会 对 这 两 个 方式 有 进一步 的 说 
明 。 第 6 音 介 绍 一 种 特殊 的 HTTP 模 块 HTTP 过 滤 模 块 的 编写 方法 。 第 7 章 探讨 基础 容器 的 
用 法 ， 这 同样 是 复杂 模块 的 必 备 工具 。 
站 由 由 有 由 由 有 有 由 站 Pttop://wNwv linuxporobe. con 





























如 果 读者 对 于 普通 HTTP 模块 的 编写 已 经 很 熟悉 ， 想 深入 地 实现 更 为 复杂 的 HITP 模 块 ， 
或 者 想 了 解 邮件 代理 服务 器 的 设计 与 实现 ， 或 者 希望 编写 一 种 新 的 处 理 其 他 协议 的 模块 ， 或 
者 仅仅 想 了 解 Nginx 的 架构 设计 ， 都 可 以 直接 从 第 8 章 开 始 学 习 ， 这 一 章 会 从 整体 上 系统 介绍 
Nginx 的 模块 式 设 计 。 第 9 章 的 事件 框架 是 Nginx 处 理 TCP 的 基础 ， 这 一 章 无 法 跳 过 。 阅 读 第 8 
章 、 第 9 章 时 可 能 会 遇 到 许多 第 7 章 介 绍 过 的 容器 ， 这 时 可 以 回 到 第 7 章 查询 其 用 法 和 意义 。 
第 10 章 ~ 第 12 章 在 介绍 HTTP 框架， 通过 这 3 章 的 学 习 会 对 HTTP 模 块 的 开发 有 深入 的 了 解 ， 同 
时 可 以 学 习 HTTP 框 架 的 优秀 设计 。 第 13 章 简单 介绍 了 邮件 代理 服务 器 的 设计 ， 它 近似 于 简 
化 版 的 HTTP 框 架 。 第 14 章 介绍 了 进程 间 同 步 的 工具 。 第 15 间 介绍 了 HTTP 变 量 ， 包 括 如 何 使 
用 已 有 变量 、 文 持 用 户 在 nginx.conf 中 修改 变量 的 值 、 支 持 其 他 模块 开发 者 使 用 自己 定义 的 变 
量 等 。 第 16 章 介绍 了 slab 共 享 内 存 ， 访 内存 极为 高 效 ， 可 用 于 多 个 worker 进 程 间 的 通信 。 





























为 了 不 让 读者 陷入 代码 的 “汪洋 大 海 ” 中 ， 在 本 书 中 大 量 使 用 了 图 表 ， 这 样 可 以 使 读者 快 
速 、 大 体 地 了 解 流 程 和 原理 ， 在 这 基础 上 ， 如 果 读 者 还 希望 了 解 代码 是 如 何 实现 的 ， 可 以 针 
对 性 地 阅读 源 代码 中 的 相应 方法 。 在 代码 的 关键 地 方 会 通过 添加 注释 的 方式 加 以 说 明 。 硕 望 
这 种 方式 能 够 帮助 读者 减少 阅读 花费 的 时 间 ， 更 快 、 更 好 地 把 握 住 Nginx， 同 时 深入 到 细 市 
中 。 














写作 本 书 第 1 版 时 ，Nginx 的 最 新 稳定 版 本 是 1.0.14， 所 以 当时 是 基于 此 版 本 来 写作 的 。 
截止 到 第 2 版 完成 时 ，Nginx 的 稳定 版 本 已 经 上 升 到 了 1.8.0。 但 这 不 会 对 本 书 的 阅读 造成 困 
惑 ， 笔 者 验证 过 示例 代码 ， 均 可 以 运行 在 最 新 版 本 的 Nginx 中 ， 这 是 因为 本 书 主要 是 在 介绍 
Nginx 的 基本 框架 代码 ， 以 及 怎样 使 用 这 些 框 架 代 码 开发 新 的 Nginx 模 块 。 在 这 些 基本 框架 代 
码 中 ，Nginx 一 般 不 会 做 任何 改变 ， 人 否则 己 有 的 大 量 Nginx 模 块 将 无 法 工作 ， 这 种 损失 是 不 可 
承受 的 。 而 且 Nginx 框 架 为 具体 的 功能 模块 提供 了 足够 的 灵活 性 ， 修 改 功 能 时 很 少 需 要 修改 
框架 代码 。 











Nginx 是 跨 平 台 的 服务 器 ， 然 而 这 本 书 将 只 针对 于 最 常见 的 Linux 操 作 系 统 进行 分 析 ， 这 
样 做 一 方面 是 篇 幅 所 限 ， 另 一 方面 则 是 本 书 的 写作 目的 主要 在 于 告诉 大 家 如 何 基于 Nginx 编 
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写 代 码 ， 而 不 是 怎样 在 一 个 具体 的 操作 系统 上 修改 配置 使 用 Nginx。 因 此 ， 即 使 本 书 以 Linux 
系统 为 代表 讲述 Nginx， 也 不 会 影响 使 用 其 他 操作 系统 的 读者 阅读 ， 操 作 系统 的 兰 别 相对 于 
本 书 内 容 的 影响 实在 是 非常 小 。 





勘误 和 文 持 


由 于 作者 的 水 平 有 限 ， 加 之 编写 的 时 间 也 很 仓促 ， 书 中 难免 会 出 现 一 些 错 误 或 者 不 准确 
的 地 方 ， 奶 请 读者 批评 指正 。 为 此 ， 我 特意 创建 了 一 个 在 线 支 持 与 应 急 方 案 的 二 级 站 
点 : http://nginx.weebly.com 。 读 者 可 以 将 书 中 的 错误 发 布 在 Bug 勘 误 表 页 面 中 ， 同 时 如 果 读 
者 遇 到 任何 问题 ， 也 可 以 访问 Q&A 页 面 ， 我 将 尽量 在 线 上 为 读者 提供 最 满意 的 解答 。 书 中 的 
全 部 源 文件 都 将 发 布 在 这 个 网 站 上 ， 我 也 会 将 相应 的 功能 更 新 及 时 发 布 出 来 。 如 果 你 有 更 多 
的 宝贵 意见 ， 也 欢迎 你 发 送 邮 件 至 我 的 邮箱 russelltao@foxmail.com， 期 竺 能 够 听 到 读者 的 真 
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第 一 部 分 Nginx 能 帮 我 们 做 什么 
` 第 1 章 ”研究 Nginx 前 的 准备 工作 


. 第 2 章 Nginx 的 配置 
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第 1 章 ”研究 Neginx 前 的 准备 工作 


2012 年 ，Nsginx 荣 获 年 度 云 计算 开发 奖 (2012 Cloud Award for Developer of the Year) ， 
并 成 长 为 世界 第 二 大 Web 服 务 器 。 全 世界 流量 最 高 的 前 1000 名 网 站 中 ， 超 过 25% 都 使 用 Nginx 
来 处 理 海量 的 互联 网 请 求 。Nginx 已 经 成 为 业界 高 性 能 Web 服 务 器 的 代名词 。 





那么 ， 什 么 是 Nginx? 它 有 了 哪些 特点 ? 我 们 选择 Nginx 的 理由 是 什么 ?如何 编译 安装 
Nginx? 这 种 安装 方式 背后 隐藏 的 又 是 什么 样 的 思想 昵 ? 本 章 将 会 回答 上 述 问题 。 
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1.1 Neginx 古 什么 


人 们 在 了 解 新 事物 时 ， 往 往 习 惯 通过 类 比 来 帮助 自己 理解 事物 的 概貌 。 那 么 ， 我 们 在 学 
习 Nsginx 时 也 采用 同样 的 方式 ， 先 来 看 看 Nginx 的 竞争 对 手 一 -Apache、Lighttpd、Tomcat、 
Jetty、IIS， 它 们 都 是 Web 服 务 器 ， 或 者 叫做 WWW (World Wide Web) 服务 器 ， 相 应 地 也 都 
具备 Web 服 务 器 的 基本 功能 :基于 REST 架 构 风 格 1 ， 以 统一 资源 描述 符 (Uniform Resource 
Identifier，URI) 或 者 统一 资源 定位 符 〈Uniform Resource Locator，URL) 作为 沟通 依据 ， 通 
过 HTTP 为 浏览 器 等 客户 端 程 序 提供 各 种 网 络 服务 。 然 而 ， 由 于 这 些 Web 服 务 器 在 设计 阶段 
就 受到 许多 局 上限， 例如 当时 的 互联 网 用 户 规模 、 网 络 带 宽 、 产 品 特点 等 局 限 ， 并 且 各 自 的 定 
位 与 发 展 方向 都 不 尽 相 同 ， 使 得 每 一 款 Web 服 务 器 的 特点 与 应 用 场合 都 很 鲜明 。 





Tomcat 和 Jetty 面 问 Java 语 言 ， 先 天 就 是 重量 级 的 Web 服 务 器 ， 它 的 性 能 与 Nginx 没 有 可 比 
性 ， 这 里 略 过 。 


HS 只 能 在 Windows 操 作 系 统 上 运行 。Windows 作 为 服务 器 在 稳定 性 与 其 他 一 些 性 能 上 都 
不 如 类 UNIX 操 作 系 统 ， 因 此 ， 在 需要 高 性 能 Web 服 务 器 的 场合 下 ，JHS 可 能 会 被 “ 冷 洲 ”。 








Apache 的 发 展 时 期 很 长 ， 而 且 是 目前 毫 无 争议 的 世界 第 一 大 Web 服 务 器 ， 图 1-1 中 是 12 年 
来 (2010~2012 年 ) 世界 Web 服 务 器 的 使 用 排名 情况 。 
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图 1-1 ” Netcraft 对 于 644275754 个 站 点 31.4M 个 域名 Web 服 务 器 使 用 情况 的 调查 结果 (2012 年 3 


月 ) 


从 图 1-1 中 可 以 看 出 ，Apache 目 前 处 于 领先 地 位 。 


Apache 有 许多 优点 ， 如 稳定 、 开 源 、 跨 平台 等 ， 但 它 出 现 的 时 间 太 长 了 ， 在 它 兴起 的 年 
代 ， 互 联网 的 产业 规模 远 远 比 不 上 今天 ， 所 以 它 被 设计 成 了 一 个 重量 级 的 、 不 支持 高 并 发 的 
Web 服 务 器 。 在 Apache 服 务 器 上 ， 如 果 有 数 以 万 计 的 并 发 HITP 请 求 同 时 访问 ， 就 会 导致 服 
务 器 上 消耗 大 量 内 存 ， 操 作 系统 内 核对 成 百 上 千 的 Apache 进 程 做 进程 间 切 换 也 会 消耗 大 量 
CPU 资源 ， 并 导致 HTTP 请 求 的 平均 啊 应 速度 降低 ， 这 些 都 决定 了 Apache 不 可 能 成 为 高 性 能 
Web 服 务 器 ， 这 也 促使 了 Lighttpd 和 Nginx 的 出 现 。 观 察 图 1-1 中 Nginx 成 长 的 曲线 ， 体 会 一 下 
Nginx 抢 占 市 场 时 的 “ 吊 吊 允 人 ” 吧 。 





Lighttpd 和 Nginx 一 样 ， 都 是 轻 量 级 、 高 性 能 的 Web 服 务 器 ， 哆 美的 业界 开发 者 比较 钟爱 
Lighttpd， 而 国内 的 公司 更 青睐 Nginx，Lighttpd 使 用 得 比较 少 。 
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在 了 解 了 Nginx 的 竞争 对 手 之 后 ， 相 信 大 家 对 Nginx 也 有 了 直观 感受 ， 下 面 让 我 们 来 正式 


© 提示 Noginx 发 音 : engine[snd3rn] 入 。 


来 目 俄 罗斯 的 Igor Sysoev 在 为 Rambler Media (http://www.rambler.ru/ ) 工作 期 间 ， 使 用 C 
语言 开发 了 Nginx。Neginx 作 为 Web 服 务 器 ， 一 直 为 俄罗斯 著名 的 门户 网 站 Rambler Media 提 供 
着 出 色 、 稳 定 的 服务 。 





Igor Sysoev 将 Nginx 的 代码 开源 ， 并 且 赋 予 其 最 自由 的 2-clause BSD-like license 器 许可 
证 。 由 于 Nginx 使 用 基于 事件 驱动 的 架构 能 够 并 发 处 理 百 万 级 别 的 TCP 连 接 ， 高 度 模块 化 的 设 
计 和 自由 的 许可 证 使 得 扩展 Nginx 功 能 的 第 三 方 模块 层出不穷 ， 而 且 优 秀 的 设计 带 来 了 极 佳 
的 稳定 性 ， 因 此 其 作为 Web 服 务 器 被 广泛 应 用 到 大 流量 的 网 站 上 ， 包 括 腾 讯 、 新 浪 、 网 易 、 
淘宝 等 访问 量 巨大 的 网 站 。 











2012 年 2 月 和 3 月 Netcraft 对 Web 服 务 絮 的 调查 如 表 1-1 所 示 ， 可 以 看 出 ，Nginx 的 市 场 份额 
越 来 越 大 。 


表 1-1 Netcraft 对 于 Web 服 务 器 市 场 占 有 率 前 4 位 软件 的 调查 (2012 年 2 月 和 3 月 ) 


TI EE 
Microsoft IIS 22 537 872 -0.06 
Google Web Server -0.03 


Nginx 是 一 个 跨 平 台 的 Web 服 务 器 ， 可 运行 在 Linux、FreeBSD、Solaris、AIX、Mac OS、 
Windows 等 操作 系统 上 ， 并 且 它 还 可 以 使 用 当前 操作 系统 特有 的 一 些 高 效 API 来 提高 自己 的 
性 能 。 





例如 ， 对 于 高 效 处 理 大 规模 并 发 连接 ， 它 支持 Linux 上 的 epoll (epoll 是 Linux 上 处 理 大 并 
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发 网 络 连 接 的 利器 ，9.6.1 节 中 将 会 详细 说 明 epoll 的 工作 原理 ) 、Solaris 上 的 event ports 和 
FreeBSD 上 的 kqueue 等 。 


又 如 ， 对 于 Linux，Nginx 支 持 其 独 有 的 sendfile 系 统 调 用 ， 这 个 系统 调用 可 以 高 效 地 把 硬 
盘 中 的 数据 发 送 到 网 络 上 〈 不 需要 先 把 便 盘 数据 复制 到 用 户 态 内 存 上 再 发 送 ) ， 这 极 大 地 减 
少 了 内 核 态 与 用 户 态 数据 间 的 复制 动作 。 








种 种 迹象 都 表明 ，Nginx 以 性 能 为 王 。 


2011 年 7 月 ，Nginx 正 式 成 立 公司 ， 由 Igor Sysoev 担 任 CTO， 立 足 于 提供 商业 级 的 Web 服 
务 器 。 


[1] 参见 Roy Fielding 博 士 的 论文 《Atchitectural Styles and the Design of Network-based Software 

Atrchitectures》， 可 在 http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm 查 看 原文 。 

[2 BSD (Berkeley Software Disttibution) 许可 协议 是 自由 软件 (开源 软件 的 一 个 子 集 ) 中 使 用 

最 广泛 的 许可 协议 之 一 。 与 其 他 许可 协议 相 比 ，BSD 许 可 协议 从 GNU 通 用 公共 许可 协议 
(GPL) 到 限制 重重 的 著作 权 (copyright) 都 要 宽松 一 些 ， 事 实 上 ， 它 跟 公 有 领域 更 为 接 

近 。BSD 许 可 协议 被 认为 是 copycenter (中 间 版 权 ) ， 界 于 标准 的 copytight 与 GPL 的 copyleft 之 

间 。2-clause BSD-like license 是 BSD 许 可 协议 中 最 宽松 的 一 种 ， 它 对 开发 者 再 次 使 用 BSD 软 件 

只 有 两 个 基本 的 要 求 : 一 是 如 果 再 发 布 的 产品 中 包含 源 代 码 ， 则 在 源 代 码 中 必须 带 有 原来 代 

码 中 的 BSD 协 议 ; 二 是 如 果 再 发 布 的 只 是 二 进 制 类 库 / 软 件 ， 则 需要 在 类 库 / 软 件 的 文档 和 版 

权 声 明 中 包含 原来 代码 中 的 BSD 协 议 。 
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1.2 ”为 什么 选择 Nginx 


为 什么 选择 Nginx? 因为 它 具 有 以 下 特 反 : 


(1) 更 快 





这 表现 在 两 个 方面 ， 一 方面 ， 在 正常 情况 下 ， 单 次 请 求 会 得 到 更 快 的 啊 应 ;为 一 方面 ， 
在 高 峰 期 (如 有 数 以 万 计 的 并 发 请 求 ) ，Nsginx 可 以 比 其 他 Web 服 务 器 更 快 地 响应 请 求 。 


实际 上 ， 本 书 第 三 部 分 中 大 量 的 篇 幅 都 是 在 说 明 Nginx 是 如 何 做 到 这 两 点 的 。 


(2) 高 扩展 性 





Nginx 的 设计 极 具 扩展 性 ， 它 完全 是 由 多 个 不 同 功能 、 不 同 层 次 、 不 同类 型 且 耦 合 度 极 
低 的 模块 组 成 。 因 此 ， 当 对 某 一 个 模块 修复 Bug 或 进行 升级 时 ， 可 以 专注 于 模块 自身 ， 无 须 
在 意 其 他 。 而 且 在 HTTP 模 块 中 ， 还 设计 了 HTTP 过 滤器 模块 : 一 个 正常 的 HTTP 模 块 在 处 理 
完 请 求 后 ， 会 有 一 串 HITP 过 滤器 模块 对 请 求 的 结果 进行 再 处 理 。 这 样 ， 当 我 们 开发 一 个 新 
的 HTTP 模块 时 ， 不 但 可 以 使 用 诸如 HTTP 核 心 模块 、events 模 块 、log 模 块 等 不 同 层次 或 者 不 
同类 型 的 模块 ， 还 可 以 原封 不 动 地 复 用 大 量 已 有 的 HTTP 过 滤器 模块 。 这 种 低 耦 合 度 的 优秀 
设计 ， 造 就 了 Nginx 庞 大 的 第 三 方 模块 ， 当 然 ， 公 开 的 第 三 方 模块 也 如 官方 发 布 的 模块 一 样 
容易 使 用 。 

















Nginx 的 模块 都 是 谍 入 到 二 进 制 文件 中 执行 的 ， 无 论 官方 发 布 的 模块 还 是 第 三 方 模块 都 
古 如 此 。 这 使 得 第 三 方 模块 一 样 具 备 极 其 优秀 的 性 能 ， 充 分 利用 Nginx 的 高 并 发 特性 ， 
此 ， 许 多 高 流量 的 网 站 都 倾 铝 于 开发 符合 目 己 业务 特性 的 定制 模块 。 








(3) 高 可 靠 性 











高 可 靠 性 是 我 们 选择 Nginx 的 最 基本 条 件 ， 因 为 Nginx 的 可 靠 性 是 大 家 有 目 共 睹 的 ， 很 多 
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家 高 流量 网 站 都 在 核心 服务 器 上 大 规模 使 用 Nginx。Nsginx 的 高 可 靠 性 来 自 于 其 核心 框架 代码 
的 优秀 设计 、 模 块 设计 的 简单 性 ， 男 外 ， 官 方 提供 的 常用 模块 都 非常 稳定 ， 每 个 worker 进 程 
相对 独立 ，master 进 程 在 1 个 worker 进 程 出 错时 可 以 快速 “ 拉 起 ”新 的 worker 子 进程 提供 服务 。 





(4) 低 内 存 消耗 


一 般 情况 下 ，10000 个 非 活 跃 的 HTTP Keep-Alive 连 接 在 Nginx 中 仅 消 耗 2.3SMB 的 内 存 ， 这 
是 Nginx 文 持 高 并 发 连接 的 基础 。 


从 第 3 章 开 始 ， 我 们 会 接触 到 Nginx 在 内 存 中 为 了 维护 一 个 HITP 连 接 所 分 配 的 对 象 ， 届 
时 将 会 看 到 ， 实 际 上 Nginx 一 直 在 为 用 户 考 虑 (尤其 古 在 高 并 发 时 〉 如 何 使 得 内 存 的 消耗 更 


I» 


人 从。 
(5) 单机 支持 10 万 以 上 的 并 发 连接 


这 是 一 个 非常 重要 的 特性 ! 随 着 互联 网 的 迅猛 发 展 和 互联 网 用 户 数 量 的 成 倍增 长 ， 各 大 
公司 、 网 站 都 需要 应 付 海量 并 有 请求 ， 一 个 能 够 在 峰值 期 顶 住 10 万 以 上 并 发 请 求 的 Server， 
无 疑 会 得 到 大 家 的 青睐 。 理 论 上 ，Nginx 文 持 的 并 发 连接 上 限 取 雇 于 内 存 ，10 万 远 未 封顶 。 
当然 ， 能 够 及 时 地 处 理 更 多 的 并 发 请 求 ， 是 与 业务 特点 紧密 相关 的 ， 本 书 第 8~11 间 将 会 详细 
说 明 如 何 实现 这 个 特点 。 











(6) 热 部 署 


master 管 理 进程 与 worker 工 作 进 程 的 分 离 设 计 ， 使 得 Nginx 能 够 提供 热 部 署 功能 ， 即 可 以 
在 7x24 小 时 不 间断 服务 的 前 提 下 ， 升 级 Nginx 的 可 执行 文件 。 当 然 ， 它 也 支持 不 停止 服务 就 
更 新 配置 项 、 更 换 日 志文 件 等 功能 。 


(7) 最 自由 的 BSD 许 可 协议 





这 是 Nginx 可 以 快速 发 展 的 强大 动力 。BSD 许 可 协议 不 只 是 允许 用 户 免 费 使 用 Nginx， 它 
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还 允许 用 户 在 自己 的 项 目 中 直接 使 用 或 修改 Nginx 源 码 ， 然 后 发 布 。 这 吸引 了 无 数 开发 者 继 
续 为 Nginx 页 献 目 己 的 智慧 。 


以 上 7 个 特 后 当然 不 是 Nginx 的 全 部 ， 拥 有 无 数 个 官方 功能 模块 、 第 三 方 功能 模块 使 得 
Nginx 能 够 满足 绝 大 部 分 应 用 场景 ， 这 些 功能 模块 间 可 以 合 加 以 实现 更 加 强大 、 复 杂 的 功 
能 ， 有 些 模块 还 文 持 Nginx 与 Perl、Lua 等 脚本 语言 集成 工作 ， 大 大 提高 了 开发 效率 。 这 些 特 
点 促使 用 户 在 寻找 一 个 Web 服 务 器 时 更 多 考虑 Nginx。 








当然 ， 选 择 Nginx 的 核心 理由 还 是 它 能 在 支持 高 并 发 请 求 的 同时 保持 高 效 的 服务 。 

如 条 Web 服 务 器 的 业务 访问 量 巨大 ， 就 需要 保证 在 数 以 百 万 计 的 请 求 同 时 访问 服务 时 ， 
用 户 可 以 获得 民 好 的 体验 ， 不 会 出 现 并 发 访问 量 达到 一 个 数字 后 ， 新 的 用 户 无 法 获取 服务 ， 
或 者 虽然 成 功 地 建立 起 了 TCP 连 接 ， 但 大 部 分 请 求 却 得 不 到 啊 应 的 情况 。 








通 遂 ， 高 峰 期 服务 器 的 访问 量 可 能 是 正常 情况 下 的 许多 倍 ， 徊 有 热 扣 事件 的 发 生 ， 可 能 
会 导致 正常 情况 下 非常 顺畅 的 服务 器 直接 “ 挂 死 ”*。 然 而 ， 如 下 在 部 署 服务 器 时 ， 束 预先 针对 
这 种 情况 进行 扩容 ， 叉 会 使 得 正常 情况 下 所 有 服务 占 的 负载 过 低 ， 这 会 造成 大 量 的 资源 浪 
费 。 因 此 ， 我 们 会 布 望 在 这 之 间 取 得 平衡 ， 也 就 是 说 ， 在 低 并 有 压力 下 ， 用 户 可 以 获得 高 速 
体验 ， 而 在 高 并 发 压力 下 ， 更 多 的 用 户 都 能 接 入 ， 可 能 访问 速度 会 下 降 ， 但 这 只 应 受制 于 市 
宽 和 处 理 器 的 速度 ， 而 不 应 该 是 服务 器 设计 导致 的 软件 瓶 山 。 





事实 上 ， 由 于 中 国 互联 网 用 户 群 体 的 数量 巨大 ， 致 使 对 Web 服 务 器 的 设计 往往 要 比 欧 类 
公司 更 加 困难 。 例 如 ， 对 于 全 球 性 的 一 些 网 站 而 言 ， 欧 美 用 户 分 布 在 两 个 半球 ， 欧 洲 用 户 活 
跃 时 ， 美 洲 用 户 通 千 在 休 妃 ， 反 之 亦 然 。 而 国内 巨大 的 用 户 群 体 则 对 业界 的 程序 员 提 出 更 高 
的 挑战 ， 早 上 9 点 和 晚上 20 点 到 24 点 这 些 时 间 段 的 并 发 请 求 压力 是 非常 巨大 的 。 尤 其 节 假 
日 、 寒 晋 假 到 来 之 时 ， 更 会 对 服务 器 提出 极 高 的 要 求 。 











另外 ， 国 内 业务 上 的 特性 ， 也 会 引导 用 户 在 同一 时 间 大 并 发 地 访问 服务 器 。 例 如 ， 许 多 
SNS 网 页 游戏 会 在 4 闻 点 网 打消 戏 次 浪 丰 者 多 从 六 等 好 友 忆 动 扣 信 这 此 会 导 到 
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服务 器 处 理 高 并 发 请 求 的 压力 增 大 。 





上 述 情形 都 对 我 们 的 互联 网 服务 在 大 并 发 压力 下 是否 还 能 够 给 予 用 户 民 好 的 体验 提出 了 
更 局 的 要 求 。 耕 要 提供 更 好 的 服务 ， 那 么 可 以 从 多 方面 入 手 ， 例 如 ， 修 改 业 务 特性 、 引 导 用 
户 从 高 峰 期 分 流 或 者 把 服务 分 层 分 级 、 对 于 不 同 并 发 压力 给 用 户 提供 不 同 级 别 的 服务 等 。 但 
最 根本 的 是 ，Web 服 务 器 要 能 文 持 大 并 发 压力 下 的 正常 服务 ， 这 才 是 关键 。 


快速 增长 的 互联 网 用 户 群 以 及 业内 所 有 互联 网 服务 提供 商 越 来 越 好 的 用 户 体验 ， 都 促使 
我 们 在 大 流量 服务 中 用 Nginx 取 代 其 他 Web 服 务 器 。Nginx 先 天 的 事件 驱动 型 设计 、 全 异步 的 
网 络 IO 处 理 机 制 、 极 少 的 进程 间 切 换 以 及 许多 优化 设计 ， 都 使 得 Nginx 天 生 善于 处 理 高 并 发 
压力 下 的 互联 网 请 求 ， 同 时 Nginx 降 低 了 资源 消耗 ， 可 以 把 服务 器 人 硬件 资源 “压榨 ”到 极致 。 
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1.3 准备 工作 


由 于 Linux 其 有 免费、 使 用 广泛 、 商 业 文 持 越 来 越 完善 等 特点 ， 本 书 将 主要 针对 Linux 上 
运行 的 Nginx 来 进行 介绍 。 需 要 说 明 的 是 ， 本 书 不 是 使 用 手册 ， 而 是 介绍 Nginx 作 为 Web 服 务 
恬 的 设计 思想 ， 以 及 如 何 更 有 效 地 使 用 Nginx 达 成 目的 ， 而 这 些 内 容 在 各 操作 系统 上 基本 是 
相通 的 “除了 第 9 半 关 于 事件 驱动 方式 以 及 第 14 章 的 进程 间 同 步 方式 在 类 UNIX 操 作 系 统 上 略 
有 不 同 以 外 ) 。 








1.3.1 ”Linux 操 作 系 统 


首先 我 们 需要 一 个 内 核 为 Linux 2.6 及 以 上 版 本 的 操作 系统 ， 因 为 Linux 2.6 及 以 上 内 核 才 
文 持 epoll， 而 在 Linux 上 使 用 select 或 poll 来 解决 事件 的 多 路 复 用 ， 是 无 法 解决 高 并 发 压力 问题 
的 。 





我 们 可 以 使 用 uname-a 命 令 来 得 询 Linux 和 内核 版 本 ， 例 如 : 


:wehf2wng001:root > uname -a 
Linux wehf2wng001 2.6.18-128.el5 #1 SMP Wed Jan 21 10:41:14 EST 2009 x86 64 x86 64 x86 64 GNU/Linux 








执行 结果 表明 内 核 版 本 是 2.6.18， 符 合 我 们 的 要 求 。 

1.3.2 ”使 用 Nginx 的 必 备 软件 
如 果 要 使 用 Nginx 的 常用 功能 ， 那 么 首先 需要 确保 该 操作 系统 上 至 少 安装 了 如 下 软件 。 
(1) GCC 编译 器 


GCC (GNU Compiler Collection) 可 用 来 编译 C 语 言 程序 。Nsginx 不 会 直接 提供 二 进 制 可 
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执行 程序 《1.2.x 挨 本 中 已 经 开 始 提供 茶 些 操作 系统 上 的 二 进 制 安装 包 了 ， 不 过 ， 本 书 探讨 如 
何 开 发 Nginx 模 块 是 必须 通过 直接 编译 源 代码 进行 的 ) ， 这 有 许多 原因 ， 本 章 后 面 会 详 述 
我 们 可 以 使 用 最 简单 的 yum 方 式 安装 GCC， 例 如 : 





yum install -y gcc 





GCC 是 必需 的 编译 工具 。 在 第 3 章 会 提 到 如 何 使 用 C++ 来 编写 Nginx HTTP 模块 ， 这 时 就 
要 用 到 G++ 编 译 器 了 。G++ 编 译 占 也 可 以 用 yum 安 装 ， 例 如 : 


yum install -~y gcc-ct+t+ 





Linux 上 有 许多 软件 安装 方式 ，yum 只 是 其 中 比较 方便 的 一 种 ， 其 他 方式 这 里 不 再 装 述 





(2) PCRE 库 


PCRE (Perl Compatible Regular Expressions，Perl 兼 容 正 则 表达 式 ) 是 由 Philip Hazel 开 发 
的 函数 库 ， 目 前 为 很 多 软件 所 使 用 ， 该 库 文 持 正 则 表达 式 。 它 由 RegEx 演 化 而 来 ， 实 际 上 ， 
Perl 正 则 表达 式 也 是 源 自 于 Henry Spencer 写 的 RegEx。 





如 果 我 们 在 配置 文件 nginx.conf 里 使 用 了 正则 表达 式 ， 那 么 在 编译 Nginx 时 束 必 须 把 PCRE 
库 编 译 进 Nginx， 因 为 Nginx 的 HTTP 模 块 要 靠 它 来 解析 正则 表达 式 。 当 然 ， 如 果 你 确认 不 会 使 
用 正则 表达 式 ， 就 不 必 安 装 它 。 其 yum 安 装 方式 如 下 : 





yum install -~-y pcre pcre-devel 


pcre-devel 是 使 用 PCRE 做 二 次 开发 时 所 需要 的 开发 库 ， 包 括 头 文件 等 ， 这 也 是 编译 Nginx 
所 必须 使 用 的 。 


(3) zlib 库 
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并 指定 对 于 某 些 类 型 (content-type) 的 HITP 啊 应 使 用 gzip 来 进行 压缩 以 减少 网 络 传输 量 ， 那 
么 ， 在 编译 时 就 必须 把 zlib 编 译 进 Nginx。 其 yum 安 装 方式 如 下 : 





yum install -~-y zlib zlib-devel 


同 理 ，zlib 是 直接 使 用 的 库 ，zlib-devel 是 二 次 开发 所 需要 的 库 。 
(4) OpenSSL 开 发 库 


如 果 我 们 的 服务 器 不 只 是 要 支持 HTTP， 还 需要 在 更 安全 的 SSL 协 议 上 传输 HTTP， 那 么 
就 需要 拥有 OpenSSL 了 。 男 外 ， 如 果 我 们 想 使 用 MD5、SHA1 等 散 列 函数 ， 那 么 也 需要 安装 
它 。 其 yum 安 装 方式 如 下 : 


yum install -~-y openssl openssl-devel 





上 面 所 列 的 4 个 库 只 是 完成 Web 服 务 器 最 基本 功能 所 必需 的 。 


Nginx 是 高 度 自由 化 的 Web 服 务 器 ， 它 的 功能 是 由 许多 模块 来 支持 的 。 而 这 些 模块 可 根据 
我 们 的 使 用 需求 来 定制 ， 如 果 某 些 模块 不 需要 使 用 则 完全 不 必 理 会 它 。 同 样 ， 如 果 使 用 了 某 
个 模块 ， 而 这 个 模块 使 用 了 一 些 类 似 zlib 或 OpenSSL 等 的 第 三 方 库 ， 那 么 就 必须 先 安装 这 些 
软件 。 


1.3.3 ”磁盘 目录 


要 使 用 Nginx， 还 需要 在 Linux 文 件 系统 上 准备 以 下 目录 。 
(1) Nginx 源 代码 存放 目录 


该 目录 用 于 放置 从 官网 上 下 载 的 Nginx 源 码 文件 ， 以 及 第 三 方 或 我 们 自己 所 写 的 模块 源 
代码 文件 。 
口 岂 日 所 有 有 和 所 掉 由 http' /wNv inuxorobe. con 








(2) Nginx 编 译 阶段 产生 的 中 间 文 件 存 放 目 录 


该 目录 用 于 放置 在 configure 命 令 执 行 后 所 生成 的 源 文件 及 目录 ， 以 及 make 命 令 执行 后 生 
成 的 目标 文件 和 最 终 连 接 成 功 的 二 进 制 文件 。 默 认 情 况 下 ，configure 命 令 会 将 该 目录 命名 为 
objs， 并 放 在 Nginx 源 代码 目录 下 。 


(3) 部署 目录 





该 目录 存放 实际 Nginx 服 务 运 行 期 间 所 需要 的 二 进 制 文件 、 配 置 文件 等 。 默 认 情 况 下 ， 
该 目录 为 /usrlocal/nginx。 


(4) 日 志文 件 存放 目录 


日 志文 件 通常 会 比较 大 ， 当 研究 Nginx 的 砌 层 架 构 时 ， 需 要 打开 debug 级 别 的 日 志 ， 这 个 
级 别 的 日 志 非 常 详细， 会 导致 日 志文 件 的 大 小 增长 得 极 快 ， 需 要 预先 分 配 一 个 拥有 更 大 磁盘 
空间 的 目录 。 


1.3.4 Linux 内 核 参数 的 优化 


由 于 默认 的 Linux 内 核 参 数 考虑 的 是 最 通用 的 场景 ， 这 明显 不 符合 用 于 文 持 高 并 发 访问 
的 Web 服 务 器 的 定义 ， 所 以 需要 修改 Linux 内 核 参数 ， 使 得 Nginx 可 以 拥有 更 高 的 性 能 。 


在 优化 内 核 时 ， 可 以 做 的 事情 很 多 ， 不 过 ， 我 们 通常 会 根据 业务 特点 来 进行 调整 ， 当 
Nginx 作 为 静态 Web 内 容 服 务 器 、 反 回 代 理 服务 器 或 是 提供 图 片 纺 略图 功能 (实时 压缩 图 片 ) 
的 服务 器 时 ， 其 内 核 参 数 的 调整 都 是 不 同 的 。 这 里 只 针对 最 通用 的 、 使 Nginx 支 持 更 多 并 发 
请 求 的 TCP 网 络 参数 做 简单 说 明 。 


首先 ， 需 要 修改 /etc/sysctl.conf 来 更 改 内 核 参 数 。 例 如 ， 最 第 用 的 配置 : 


fs.file-max = 999999 
net. 


oc FEE EN http: // ww | i nuxporobe. con 





net .ipv4.tcp fin timeout = 30 

net .ipv4.tcp max tw buckets = 5000 
net.ipv4.ip local port range = 1024 61000 
net.ipv4.tcp rmem = 4096 32768 262142 
net.ipv4.tcp wmem = 4096 32768 262142 
net.core.netdev max backlog = 8096 
net.core.rmem default = 262144 
net.core.wmem default = 262144 
net.core.rmem max = 2097152 
net.core.wmem max = 2097152 
net.ipv4.tcp syncookies = 1 
net.ipv4.tcp max syn.backlog=1024 

















然后 执行 sysctl-p 命 令 ， 使 上 述 修 改 生效 。 
上 面 的 参数 意义 解释 如 下 : 


. fle-max: 这 个 参数 表示 进程 (比如 一 个 worker 进 程 ) 可 以 同时 打开 的 最 大 句柄 数 ， 这 
个 参数 直接 限制 最 大 并 发 连接 数 ， 需 根据 实际 情况 配置 。 


.tcp_tw_teuse: 这 个 参数 设置 为 1， 表 示 允 许 将 TIME-WAIT 状 态 的 socket 重 新 用 于 新 的 
TCP 连 接 ， 这 对 于 服务 器 来 说 很 有 意义 ， 因 为 服务 器 上 总 会 有 大 量 TIME-WAIT 状 态 的 连接 。 


.tcp_keepalive_time: 这 个 参数 表示 当 keepalive 启 用 时 ，TCP 发 送 keepalive 消 息 的 频 度 。 
默认 是 2 小 时 ， 若 将 其 设置 得 小 一 些 ， 可 以 更 快 地 清理 无 效 的 连接 。 


* tcp_fin_timeout: 这 个 参数 表示 当 服 务 器 主动 关闭 连接 时 ，socket 保 持 在 FIN-WAIT-2 状 


态 的 最 大 时 间 。 


* tcp_max_tw_buckets: 这 个 参数 表示 操作 系统 允许 TIME_WAIT 套 接 字 数量 的 最 大 值 ， 
如 果 超 过 这 个 数字 ，TIME_WAIT 套 接 字 将 立刻 被 清除 并 打印 警告 信息 。 该 参数 默认 为 


180000， 过 多 的 TIME_WAIT 套 接 字 会 使 Web 服 务 器 变 慢 。 


.tcp_max_syn_backlog: 这 个 参数 表示 TCP 三 次 握手 建立 阶段 接收 SYN 请 求 队列 的 最 大 
长 度 ， 默 认为 1024， 将 其 设置 得 大 一 些 可 以 使 出 现 Nginx 繁 忙 来 不 及 accept 新 连接 的 情况 时 ， 
Linux 不 至 于 丢失 客户 端 发 起 的 连接 请 求 。 
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.ip_local_portt_ tange: 这 个 参数 定义 了 在 UDP 和 TCP 连 接 中 本 地 (不 包括 连接 的 远 端 ) 
端口 的 取 值 范围 。 


.het:ipv4.tcp_fmem: 这 个 参数 定义 了 TCP 接 收 缓存 (用 于 TCP 接 收 滑 动 窗口 ) 的 最 小 
值 、 默 认 值 、 了 最 大 值 。 


.netipv4.tcp_wmem: 这 个 参数 定义 了 TCP 发 送 缓存 (用 于 TCP 发 送 滑动 窗口 ) 的 最 小 
值 、 上 默认 值 、 最 大 值 。 


` netdev_max_backlog: 当 网 卡 接收 数据 包 的 速度 大 于 内 核 处 理 的 速度 时 ,会 有 一 个 队列 
保存 这 些 数 据 包 。 这 个 参数 表示 该 队列 的 最 大 值 。 


` rmem_default: 这 个 参数 表示 内 核 套 接 字 接收 缓存 区 默认 的 大 小 。 
-wmem_default: 这 个 参数 表示 内 核 套 接 字 发 送 缓存 区 默认 的 大 小 。 
` rmem_max: 这 个 参数 表示 内 核 套 接 字 接收 缓存 区 的 最 大 大 小 。 

` wmem_max: 这 个 参数 表示 内 核 套 接 字 发 送 缓存 区 的 最 大 大 小 。 


@@ 注意 滑动 窗口 的 大 小 与 套 接 字 缓 存 区 会 在 一 定 程度 上 影响 并 发 连接 的 数目 。 每 个 
TCP 连 接 都 会 为 维护 TCP 滑 动 窗口 而 消耗 内 存 ， 这 个 窗口 会 根据 服务 器 的 处 理 速度 收缩 或 扩 
张 。 


参数 wmem_max 的 设置 ， 需 要 平衡 物理 内 存 的 总 大 小 、Nginx 并 发 处 理 的 最 大 连接 数量 
(由 nginx.conf 中 的 worker_processes 和 worker_connections 参 数 决 定 ) 而 确定 。 当 然 ， 如 果 仅 仅 
为 了 提高 并 发 量 使 服务 器 不 出 现 Out Of Memory 问 题 而 去 降低 滑动 窗口 大 小 ， 那 么 并 不 合 
适 ， 因 为 滑动 窗口 过 小 会 影响 大 数据 量 的 传输 速度 。rmem_default、wmem_default、 
rmem_max、wmem_max 这 4 个 参数 的 设置 需要 根据 我 们 的 业务 特性 以 及 实际 的 硬件 成 本 来 综 
合 考 虑 。 
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. tcp_syncookies: 该 参数 与 性 能 无 关 ， 用 于 解决 TCP 的 SYN 攻 击 。 
1.3.5 ”获取 Nginx 源 人 码 


可 以 在 Nginx 官 方 网 站 《http://nginx.org/en/download.html ) 获取 Nginx 源 码 包 。 将 下 载 的 
nginx-1.0.14.tar.gz 源 人 码 压缩 包 放 置 到 准备 好 的 Nginx 源 代码 目录 中 ， 然 后 解压 。 例 如 : 





tar -ZXVE nginx-1.0.14.tar.gz 














本 书 编写 时 的 Nginx 最 新 稳定 版 本 为 1.0.14《〈 如 图 1-2 所 示 ) ， 本 书后 续 部 分 都 将 以 此 版 
本 作为 基准 。 当 然 ， 本 书 将 要 说 明 的 Nginx 核 心 代码 一 般 不 会 有 改动 (否则 大 量 第 三 方 模块 
的 功能 就 无 法 保证 了 ) ， 即 使 下 载 其 他 厂 本 的 Nginx 源 码 包 也 不 会 影响 阅读 本 书 。 


nginx: download 
Development version 
CHANGES nginX-1.1.17 pep ngsinx/Windows-1.1.17 pgp 
Stable version 
CHANGES-1.0 nginx-1.0.14 pgp nginx/Windows-1.0.1 
Legacy versions 
CHANGES-0.8 nginxX-0.8.55 pgp nginx/WindoWws-0.8.55 pgp 
CHANGES-0.7 nginx-0.7.009 pep Inx/ Wi VS-0.7.60 pgp 
CHANGES-0.6 nginx-0.6.59 pgp 














CHANGES-0.5 ngsinXx-0.5.38 pgp 


图 1-2 Nginx 的 不 同 版 本 
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1.4 编 详 安 痛 Nginx 


安装 Nginx 最 简单 的 方式 是 ， 进 入 nginx-1.0.14 目 录 后 执行 以 下 3 行 命令 : 


./configure 
make 
make install 














configure 命 令 做 了 大 量 的 “幕后 ”工作 ， 包 括 检 测 操作 系统 内 核 和 已 经 安 钱 的 软件 ， 参 数 
的 解析 ， 中 间 目 录 的 生成 以 及 根据 各 种 参数 生成 一 些 C 源 码 文件 、Makefile 文 件 等 。 


make 命 令 根 据 configure 命 令 生成 的 Makefile 文 件 编译 Nginx 工 程 ， 并 生成 目标 文件 、 最 终 
的 二 进 制 文件 。 


make install 命 令 根据 configure 执 行 时 的 参数 将 Nginx 部 车 到 指定 的 安装 目录 ， 包 括 相关 目 
录 的 建立 和 二 进 制 文件 、 配 置 文件 的 复制 。 
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1.5 configure 详 解 


可 以 看 出 ，configure 命 令 至 关 重 要 ， 下 文 将 详细 介绍 如 何 使 用 configure 命 令 ， 并 分 析 
configure 到 底 是 如 何 工 作 的 ， 从 中 我 们 也 可 以 看 出 Nginx 的 一 些 设计 思想 。 


1.5.1 ”configure 的 命令 参数 


使 用 help 命 令 可 以 查看 configure 包 含 的 参数 。 
./configure --help 


这 里 不 一 一 列 出 help 的 结果 ， 只 是 把 它 的 参数 分 为 了 四 大 类 型 ， 下 面 将 会 详 述 各 类 型 下 
所 有 参数 的 用 法 和 意义 。 


1. 路 径 相关 的 参数 
表 1-2 列 出 了 Nginx 在 编译 期 、 运 行 期 中 与 路 径 相关 的 各 种 参数 。 


表 1-2 configure 支 持 的 路 径 相 关 参 数 
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参数 名 称 


--prefix=PATH 


--Sbin-path=PATH 
--Conf-path=PATH 


--error-log-path=PATH 


--pid-path=PATH 


--lock-path=PATH 


--builddir=DIR 


--With-perl_ modules path=PATH 


--with-perl=PATH 


--http-log-path=PATH 


--http-client-body-temp-path=PATH 


--http-proxy-temp-path=PATH 


Nginx 安装 部 署 后 的 根 目录 


可 执行 文件 的 放置 路 径 

配置 文件 的 放置 路 径 

error 日 志文 件 的 放置 路 径 。error 日 志 
用 于 定位 问题 ， 可 输出 多 种 级 别 (包括 
debug 调试 级 别 ) 的 日 志 。 它 的 配置 非常 
灵活 ， 可 以 在 nginx.conf 里 配置 为 不 同 请 
求 的 日 志 并 输出 到 不 同 的 log 文件 中 。 这 
里 是 默认 的 Nginx 核心 日 志 路 径 

pid 文件 的 存放 路 径 。 这 个 文件 里 仅 以 
ASC IT 公 存放 着 Nginx master 的 进程 ID， 
有 了 这 个 进程 ID， 在 使 用 命令 行 (例如 
nginx -s reload) 通过 读 取 master 进程 ID 
向 master 进程 发 送信 号 时 ， 才 能 对 运行 中 
的 Nginx 服务 产生 作用 

lock 文件 的 放置 路 径 

configure 执行 时 与 编译 期 间 产 生 的 临时 
文件 放置 的 目录 ， 包 括 产 生 的 Makefile、 
C 源 文件 、 目 标 文件 、 可 执行 文件 等 

perl module 放置 的 路 径 。 只 有 使 用 了 第 

: 方 的 perl module， 才 需要 配置 这 个 路 径 

perl binary 放置 的 路 径 。 如 果 配 置 的 Nginx 
会 执行 Perl 脚本 ， 那 么 就 必须 要 设置 此 路 径 

access 日志 放置 的 位 置 。 每 一 个 HTTP 
请 求 在 结束 时 都 会 记录 的 访问 日 志 

处 理 HTTP 请 求 时 如 果 请 求 的 包 体 需要 
暂时 存放 到 临时 磁盘 文件 中 ， 则 把 这 样 的 
临时 文件 放置 到 该 路 径 下 

Nginx 作 为 HTTP 反 向 代理 服务 器 时 ， 
上 游 服务 器 产生 的 HTTP 包 体 在 需要 临时 
存放 到 磁盘 文件 时 ( 详 见 12.8 节 )， 这 样 
的 临时 文件 将 放 到 该 路 径 下 





默认 值 
默认 为 /usr/local/nginx 目录 。 注 
意 : 这 个 目标 的 设置 会 影响 其 他 参 
数 中 的 相对 目录 。 例 如 ， 如 果 设 
置 了 --sbin-path=sbin/nginx， 那 么 
实际 上 可 执行 文件 会 被 放 到 /usr/ 


local/nginx/sbin/nginx 中 
<prefix>/sbin/nginx 


<prefix>/conf/nginx.conf 


<prefix>/logs/error.log 


<prefix>/logs/nginx.pid 


<prefix>/logs/nginx.lock 


<nginx source path>/objs 


无 


无 


<prefix>/logs/access.log 


<prefix>/client_body_ temp 


<prefix>/proxy_temp 
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参数 名 称 
--http-fastcgi-temp-path=PATH 
--http-uwsgi-temp-path=PATH 
--http-scgi-temp-path=PATH 


2. 编 译 相关 的 参数 


Fastcgi 所 使 用 临时 文件 的 放置 目录 


uWSGI 所 使 用 临时 文件 的 放置 目录 
SCGI 所 使 用 临时 文件 的 放置 目录 





表 1-3 列 出 了 编译 Nginx 时 与 编译 器 相关 的 参数 。 


编译 参数 
--With-cc=PATH 
--With-cpD=PATH 


--With-cc-opt=OPTIONS 


需要 包含 人 


t E 
数 


opt=llibraryName -LlibraryPath, 


--with-ld-opt=OPTIONS 


标语 


--With-cpu-opt=CPU 


指定 CPU 处 理 需 架构 ， 
pentium4 、 


表 1-3 configute 支 持 的 编译 相关 参数 


意 义 

C 编译 央 的 路 径 

C 预 编 译 怖 的 路 径 

如 果 和 希望 在 Nginx 编译 期 间 指定 加 入 : 

的 目录 ， 这 时 可 以 使 用 该 参数 达成 目的 

最 终 的 二 进 制 可 执行 文件 】 
执行 链接 操作 时 可 能 会 需要 指定 链接 参数 ， 

例如 ， 如 果 我 们 希望 将 某 个 

其 中 libraryName } 

= 所 在 的 路 径 

只 能 从 以 下 取 值 中 选择 : 
sparc32、 


athlon 、opteron.、 


3. 依 赖 软件 的 相关 参数 


表 1-4~ 表 1-8 列 出 了 Nginx 依 赖 的 第 用 软件 支持 的 参数 。 


PCRE 库 的 设置 参数 
--without-pcre 


--With-pcre 
--With-pcre=DIR 
--with-pcre-opt=OPTIONS 


表 1-4 PCRE 的 设置 参数 


意 义 
如 条 确认 Nginx 不 用 解析 正则 表达 式 ， 也 就 是 说 ， 
现 正则 表达 式 ， 那 么 可 以 使 用 这 个 参数 


强制 使 用 PCRE 库 
指定 PCRE 库 的 源码 位 置 ， 
编译 PCRE 源码 时 希望 加 入 的 编译 选项 


- 些 编译 选项 ， 


是 由 编 详 后 生成 的 目标 文 
--With-ld-opt 就 是 
库 链 接 到 Nginx 程序 中 ， 
记 目 标 库 的 名 称 ， 


pentiunml、 
sparc64 、ppc64 


默认 值 
<prefix>/fastcg1 temp 
<prefix>/uwsgl temp 


<prefix>/scg1 temp 


如 指定 宏 或 者 使 用 - 


件 与 


些 第 三 ; 


nginx.conf We 


NE 
A 
7 


I 加 入 基 些 


方 库 链接 生 Ry 
:用 于 加 入 链接 时 的 参 
需要 在 这 里 加 入 --with-ld- 
libraryPath 则 是 目 


pentiumpro 、pentium3 、 


文件 中 不 会 出 


在 编译 Nginx 时 会 进入 该 目录 编译 PCRE 源码 
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表 1-5 OpenSSL 的 设置 参数 


OpenSSL 库 的 设置 参数 意 义 
指定 OpenSSL 库 的 源码 位 置 ， 在 编译 Nginx ph 目录 编译 OpenSSL 源码 
--with-openssl=DIR 注意 : 如 果 Web 服务 器 支持 HTTPS， 也 就 是 SSL 协议 ，Nsginx 要 求 必须 使 
用 OpenSSL。 可 以 访问 http://www.openssl.org/ 免费 下 载 
--with-openssl-opt=OPTIONS 编译 OpenSSL 源码 时 希望 加 入 的 编译 选项 


表 1-6 原子 库 的 设置 参数 


atomic ( 原子) 库 的 设置 参数 意 义 
强制 使 用 atomic 库 。atomic 库 是 CPU 架构 独立 的 一 种 原子 操作 的 实现 。 它 支持 
--with-libatomic 以 下 体系 架构 : x86 (包括 1386 和 x86 64 )、PPC64、 en (V9 或 更 高 版 本 ) 或 
者 安装 了 GCC 4.1.0 及 更 高 版 本 的 架构 。14.3 节 介 绍 了 原子 操作 在 Nginx 中 的 实现 
--with-libatomic=DIR atomic 库 所 在 的 位 置 


表 1-7 散 列 函数 库 的 设置 参数 


散 列 函数 库 的 设置 参数 意 义 
指定 MD5 库 的 源码 位 置 ， 在 编译 Nginx 时 会 进入 该 目录 编译 MD5 源码 
--With-MDS=DIR. 注意 : Nginx 源 已 经 有 了 MD5 算法 的 实现 ， 如 果 没 有 特殊 需求 ， 那 么 完 
全 可 以 使 用 Nginx 日 身 实 现 的 MD5S 算法 
--with-MD5-opt=OPTIONS 编译 MD5 源码 时 希望 加 入 的 编译 选项 
---With-MD5-asm 使 用 MDS 的 汇编 源码 
指定 SHA1 库 的 源码 位 置 ， 在 编译 Nginx 时 会 进入 该 目录 编译 SHA1 源码 
--with-SHA1=DIR 注意 : OpenSSL 中 已 经 有 了 SHA1 算法 的 实现 。 如 果 已 经 安装 了 OpenSSL， 
那么 完全 可 以 使 用 OpenSSL 实现 的 SHA1 算法 
--with-SHA1-opt=OPTIONS 编译 SHA1 源码 时 希望 加 入 的 编译 选项 
--With-SHA1-asm 使 用 SHAI 的 汇编 源码 


表 1-8 zlb 库 的 设置 参数 


zlib 库 的 设置 参数 意 义 

指定 zlib 库 的 源码 位 置 ， 在 编译 Nginx 时 会 进入 该 目录 编译 zlib 源码 。 如 果 使 
用 了 gzip 压缩 功能 ， 就 需要 zlib 库 的 支持 
--with-zlib-opt=OPTIONS 编译 zlib 源码 时 希望 加 入 的 编译 选项 

指定 对 特定 的 CPU 使 用 zlib 库 的 汇编 优化 功能 ， 目 前 仅 支 持 两 种 架构 : pentium 
和 pentiumpro 


--With-zlib=DIR 


--With-zlib-asm=CPU 


4. 模 块 相关 的 参数 
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除了 少量 核心 代码 外 ，Nginx 完 全 是 由 各 种 功能 模块 组 成 的 。 这 些 模 块 会 根据 配置 参数 
决定 自己 的 行为 ， 因 此， 正确 地 使 用 各 个 模块 非常 关键 。 在 configure 的 参数 中 ， 我 们 把 它们 
分 为 五 大 类 。 


" 事件 模块 。 

: 默认 即 编译 进入 Nginx 的 HTTP 模 块 。 

默认 不 会 编译 进入 Nginx 的 HTTP 模 块 。 

邮件 代理 服务 器 相关 的 mail 模 块 。 

` 其 他 模块 。 

(1) 事件 模块 

表 1-9 中 列 出 了 Nginx 可 以 选择 哪些 事件 模块 编译 到 产品 中 。 


表 1-9 configute 支 持 的 事件 模块 参数 
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区 
预 
溢 
测 


义 
使 用 rtsig module 处 理事 件 驱 动 
--with-rtsig module 默认 情况 下 ，Nsginx 是 不 安装 rtsig module 的 ， 即 不 会 把 rtsig module 编译 进 最 终 的 
Nginx 二 进 制 程序 中 
使 用 select module 处 理事 件 驱 动 
select 是 Linux 提供 的 一 种 多 路 复 用 机 制 ， 在 epoll 调用 没有 诞生 前 ， 例 如 在 Linux 
--with-select module 2.4 及 其 之 前 的 内 核 中 ，select 用 于 支持 服务 需 提 供 高 并 发 连接 
默认 情况 下 ，Nsginx 是 不 安装 select module 的 ， 但 如 果 没 有 找到 其 他 更 好 的 事件 模 
块 ， 该 模块 将 会 被 安装 


--without-select module 不 安装 select module 
使 用 poll module 处 理事 件 驱 动 
--wWith-poll module poll 的 性 能 与 select 类 似 ， 在 大 量 并 发 连接 下 性 能 都 远 不 如 epoll。 上 默认 情况 下 ， 


/ 
» 


Nginx 是 不 安装 poll module 的 
--without-poll module 不 安装 poll module 
使 用 AIO 方式 处 理事 件 驱 动 
注意 : 这 里 的 aio module 只 能 与 FreeBSD 操作 系统 上 的 kqueue 事件 处 理 机 制 合 作 ， 
Linux 上 无 法 使 用 


默认 情况 下 是 不 安装 aio module 的 


--With-aio module 


(2) 默认 即 编译 进入 Nginx 的 HTTP 模 块 


表 1-10 列 出 了 默认 就 会 编译 进 Nginx 的 核心 HTTP 模 块 ， 以 及 如 何 把 这 些 HTTP 模 块 从 产品 
中 去 除 。 


表 1-10 ”configure 中 默认 编译 到 Neginx 中 的 HTTP 模 块 参数 
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默认 安装 的 HTTP 模块 


--without-http_charset module 


--Without-http_gzip_ module 


--Without-http_ ssl module 


--without-http_userid module 


--Without-http_access_ module 


--without-http_auth basic module 


--without-http_autoindex module 


--without-http_geo module 


意 义 
个 模块 


不 安装 http charset module 模块 可 以 将 服务 顺 发 出 的 HITP 啊 应 
重 编 但 
不 安装 http gzip module。 在 服务 需 发 出 的 HTTP 啊 应 包 中 ， 这 个 模块 


可 以 按照 配置 文件 指定 的 content-type 对 特定 大 小 的 HTTP 响应 包 体 执行 


gzip 压缩 


不 安装 http ssi module。 该 模块 可 以 在 向 用 户 返 回 的 HTTP 响应 包 体 中 
加 入 特定 的 内 容 ， 如 HTML 文件 中 国定 的 页 头 和 页 尾 

不 安装 http userid module。 这 个 模块 可 以 通过 HTTP 请 求 头 部 信息 里 的 
一 些 字段 认证 用 户 信 息 ， 以 确定 请 求 是 否 合法 

不 安装 http access module。 这 个 模块 可 以 根据 耳 地 址 限制 能 够 访问 服 
务 融 的 客户 端 

不 安装 http auth basic module。 这 个 模块 可 以 提供 最 简单 的 用 户 名 / 密 
公认 证 

不 安装 http autoindex module。 该 模块 提供 简单 的 目录 浏览 功能 

不 安装 http geo module。 这 个 模块 可 以 定义 一 些 变量 ， 这 些 变量 的 值 将 
与 客户 端 IP 地 址 关联 ， 这 样 Nginx 针对 不 同 的 地 区 的 客户 端 (根据 IP 


地 址 判断 ) 返回 不 一 样 的 结果 ， 例 如 不 同 地 区 显示 不 同 语言 的 网 页 
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默认 安装 的 HTTP 模块 


--wWithout-http map_ module 


--without-http split clients module 


--Without-http_referer module 


--Without-http rewrite module 


--without-http_proxy_ module 
--Without-http_fastcgi module 
--without-http_ uwsgi module 


--Without-http scgi module 


--wWithout-http memcached module 


--without-http limit zone module 


--Without-http_limit req_ module 


--without-http_empty_gif module 


--without-http_ browser module 


--without-http upstream ip hash module 


( 续 ) 


意 义 

不 安装 http map module。 这 个 模块 可 以 建立 一 个 key/value 映射 表 ， 不 
同 的 key 得 到 相应 的 value， 这 样 可 以 针对 不 同 的 URL 做 特殊 处 理 。 例 
如 ， 返 回 302 重 定向 响应 时 ， 可 以 期 望 URL 不 同时 返回 的 Location 字段 
也 不 一 样 

不 安装 http split client module。 该 模块 会 根据 客户 端的 信息 ， 例 如 卫 
地 址 、header 头 、cookie 等 ， 来 区 分 处 理 

不 安装 http referer module。 该 模块 可 以 根据 请 求 中 的 referer 字段 来 拒 
绝 请 求 

不 安装 http rewrite module。 该 模块 提供 HTTP 请 求 在 Nginx 服务 内 部 
的 重 定向 功能 ,依赖 PCRE 库 

不 安装 http proxy module。 该 模块 提供 基本 的 HTTP 反问 代理 功能 

不 安装 http fastcgi module。 该 模块 提供 FastCGI 功能 

不 安装 http uwsgi module。 该 模块 提供 uWSGI 功能 

不 安装 http scgi module。 该 模块 提供 SCGI 功能 

不 安装 http memcached module- 该 模块 可 以 使 得 Nginx 直接 由 上 游 的 
memcached 服务 读 取 数 据 ， 并 简单 地 适 配 成 HTTP 啊 应 返回 给 客户 端 

不 安装 http limit zone module。 该 模块 针对 某 个 IP 地 址 限制 并 发 连接 
数 。 例 如 , 使 Nginx 对 一 个 IP 地 址 仅 允 许 一 个 连接 

不 安装 http limit req module。 该 模块 针对 某 个 IP 地 址 限制 并 发 请 求 数 

不 安装 http empty gif module。 该 模块 可 以 使 得 Nginx 在 收 到 无 效 请 求 
时 ， 立 刻 返 回 内 存 中 的 1x 1 像素 的 GIF 图 片 -: 这 种 好 处 在 于 ， 对 于 明显 
的 无 效 请 求 不 会 去 试图 浪费 服务 器 资源 

不 安装 http browser module- 该 模块 会 根据 HTTP 请 求 中 的 user-agent 
字段 (该 字段 通常 由 浏览 器 十 写 ) 来 识别 浏览 器 

不 安装 http upstream ip hash module。 该 模块 提供 当 Nginx 与 后 端 server 
建立 连接 时 ,会 根据 卫 做 散 列 运算 来 决定 与 后 端 哪 台 server 通信 ， 这 样 
可 以 实现 负载 均衡 


(3) 默认 不 会 编译 进入 Nginx 的 HTTP 模 块 


表 1-11 列 出 了 默认 不 会 编译 至 Nginx 中 的 HTTP 模 块 以 及 把 它们 加 入 产品 中 的 方法 。 


表 1-11 configure 中 默认 不 会 编译 到 Noginx 中 的 HTTP 模 块 参数 
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可 选 的 HTTP 模块 意 义 
安装 http ssl module。 该 模块 使 Nginx 支持 SSL 协议 ， 提 供 HTTPS 服务 

--with-http_ssl module 注意 : 该 模块 的 安装 依赖 于 OpenSSL 开源 软件 ， 即 首先 应 确保 已 经 在 之 前 
的 参数 中 配置 了 OpenSSL 

安装 http realip module。 该 模块 可 以 从 客户 端 请 求 里 的 header 信息 (如 
X-Real-IP 或 者 X-Forwarded-For) 中 获取 直 正 的 客户 端 卫 地 址 

安装 http addtion module。 该 模块 可 以 在 返回 客户 端的 HITP 包 体 头 部 或 者 
尾部 增加 内 容 


--with-http_realip _ module 


--with-http_addition module 
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可 选 的 HTTP 模块 


--With-http Xslt module 


--With-http_ image _filter module 


--wWith-http_&geoip module 


--wWith-http Sub module 


—With-http_dav_module 


--wWith-http_flv module 


--wWith-http_ mp4 module 


-=-with-http gzip static module 


—With-http_ random index module 


--With-http secure link module 


--wWith-http degradation module 


--with-http stub status module 


--with-google_ perftools module 


( 续 ) 
意 义 

安装 http xslt module。 这 个 模块 可 以 使 XML 格式 的 数据 在 发 给 客户 端 前 加 
人 XSL 演 染 

注意 : 这 个 模块 依赖 于 libxml2 和 libxslt 库 ， 安 装 它 前 首先 确保 上 述 两 个 
软件 已 经 安装 

安装 http image_filter module。 这 个 模块 将 符合 配置 的 图 片 实时 压缩 为 指定 
大 小 (width*height) 的 缩 略 图 再 发 送 给 用 户 ， 目 前 支持 JPEG ,PNG ,GIF 格式 

注意 : 这 个 模块 依赖 于 开源 的 libgd 库 ， 在 安装 前 确保 操作 系统 已 经 安装 了 
libgd 

安装 http geoip module。 该 模块 可 以 依据 MaxMind GeolP 的 IP 地 址 数据 库 
对 客户 端的 IP 地 址 得 到 实际 的 地 理 位 置信 息 

注意 ; 该 库 依 不 于 MaxMind GeolP 的 库 文件 ， 可 访问 http://geolite.maxmind. 
com/download/geoip/database/GeoLiteCity.dat.gz 获取 

安装 http sub module。 该 模块 可 以 在 Nginx 返回 客户 端的 HTTP 响应 包 中 
将 指定 的 字符 串 蔡 换 为 日 已 需要 的 字符 串 

例如 ， 在 HIML 的 返回 中 ， 将 Shead> 替换 为 </head><script language= javascript" 
strc="$script"></script> 

安装 http dav module。 这 个 模块 可 以 让 Nginx 支持 Webdav 标准 ， 
Webdav 协议 中 的 PUT、DELETE、COPY、MOVE、MKCOL 等 请 求 

安装 http flv module。 这 个 模块 可 以 存 向 客户 端 返 回响 应 时 ， 对 FLV 格式 
的 视频 文件 在 header 头 做 一 些 人 处 理 ， 使 得 客户 端 可 以 观看 、 拖 动 FLV 视频 

安装 http mp4 module。 该 模块 使 客户 端 可 以 观看 、 拖 动 MP4 视频 

安装 http gzip static module- 如 果 采 用 gzip 模块 把 一 些 文档 进行 gzip 格式 
压缩 后 再 返回 给 客户 端 ， 那么 对 同一 个 文件 每 次 都 会 重新 压缩 ， 这 是 比较 消 
杆 服 务 大 CPU 资源 的 。gzip static 模块 可 以 在 做 gzip 压缩 前 ， 先 查看 相同 位 
置 是 否 有 已 经 做 过 gzip 压缩 的 .gz 文件， 如 果 有 、 就 直接 返回 。 这 样 就 可 以 
预先 在 服务 器 上 做 好 文档 的 压缩 ,给 CPU 减负 

安装 http random index module。 该 模块 在 客户 端 访问 基 个 目录 时 ， 随 机 返 
回 该 目录 下 的 任意 文件 

安装 http secure link module。 该 模块 提供 一 种 验证 请 求 是 否 有 效 的 机 制 。 
例如 ， 它 会 验证 URL 中 需要 加 入 的 token 参数 是 否 届 于 特定 客户 端 发 来 的 ， 
以 及 检查 时 间 鹤 是 否 过 期 

安装 http degradation module。 该 模块 针对 一 些 特 殊 的 系统 调用 (如 sbrk) 
做 一 些 优化 ， 如 直接 返回 HTTP 响应 码 为 204 或 者 444。 目 前 不 支持 Linux 
系统 

安装 http stub status module。 该 模块 可 以 让 运行 中 的 Nginx 提供 性 能 统计 
页 面 ， 获 取 相 关 的 并 发 连接 、 请 求 的 信息 ( 14.2.1 节 中 简单 介绍 了 该 模块 的 
原理 ) 

安装 google perftools module。 该 模块 提供 Google 的 性 能 测试 工具 


如 支持 


(4) 邮件 代理 服务 器 相关 的 mail 模 块 
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表 1-12 列 出 了 把 邮件 模块 编译 到 产品 中 的 参数 。 


表 1-12 configute 提 供 的 邮件 模块 参数 


可 选 的 mail 模块 意 义 
安装 邮件 服务 器 反 向 人 ee 使 Nginx 可 以 反问 代理 IMAP、POP3、SMTP 


--With-mail 


等 协议 。 该 模块 默认 不 安装 

安装 mail ssl module 该 块 可 以 使 IMAP、POP3、SMTP 等 协议 基于 SSL/ 
TLS 协议 之 上 使 用 。 该 模块 默认 不 安装 并 依赖 于 OpenSSL 库 

不 安装 mail pop3 module。 在 使 用 --with-mail 参数 后 ，pop3 module 是 默认 安 
装 的 ， 以 使 Nginx 支持 POP3 协议 

不 安装 mail imap module。 在 使 用 --with-mail 参数 后 ，imap module 是 默认 安 
装 的 ， 以 使 Nginx 支持 IMAP 

不 安装 mail smtp module。 在 使 用 --with-mail 参数 后 ，smtp module 是 默认 安 
装 的 ， 以 使 Nginx 支持 SMTP 


--With-mail ssl module 
--Without-mail pop3_ module 
--without-mail imap module 


--without-mail smtp module 


5. 其 他 参数 
configure 还 接收 一 些 其 他 参数 ， 表 1-13 中 列 出 了 相关 参数 的 说 明 。 


表 1-13 configure 提 供 的 其 他 参数 


其 他 一 些 参 数 意 义 
将 Nginx 需要 打印 debug 调试 级 别 日 志 的 代码 编译 进 Nginx。 这 样 可 以 在 Nginx 运行 


--With-debug a We wg We a 
证 


--add-module=PATH 在 和 和 ee 0 让 人 
--without-http 株 用 HTTP 服务 响 
--without-http-cache 森 用 HTTP 服务 器 里 的 缓存 Cache 特性 
--with-file-aio 启用 文件 的 异步 IO 功能 来 处 理 磁盘 文件 ， 这 需要 Linux 内 核 支 持原 生 的 异步 IO 
--With-ipv6 使 Nginx 支持 IJPv6 
指定 Nginx worker 进程 运行 时 所 属 的 用 户 
--UseI=USER 注意 : 不 要 将 启动 worker 进程 的 用 户 设 为 root， 在 worker 进程 出 问题 时 master 进程 
要 具备 停止 / 启动 worker 进程 的 能 力 
--group=GROUP 指定 Nginx worker 进程 运行 时 所 属 的 组 


1.5.2 ”configure 执 行 流程 
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我 们 看 到 configure 命 令 支 持 非常 多 的 参数 ， 读 者 可 能 会 好 奇 它 在 执行 时 到 底 做 了 哪些 事 
情 ， 本 节 将 通过 解析 configure 源 码 来 对 它 有 一 个 感性 的 认识 。configure 由 Shell 脚 本 编写 ， 中 
间 会 调用 <nginx-source>/auto/ 目 录 下 的 脚本 。 这 里 将 只 对 configure 脚 本 本 刁 做 分 析 ， 对 于 它 所 
调用 的 auto 目 录 下 的 其 他 工具 脚本 则 只 做 功能 性 的 说 明 。 


configure 脚 本 的 内 容 如 下 : 





#!/bin/sh 

# Copyright (C) Igor Sysoev 
# Copyright (C) Nginx, Inc. 
#auto/options 脚 本 处 理 


configure 命 令 的 和 参数。 例如， 如 果 参 数 是 
--help， 那 么 显示 支持 的 所 有 参数 格式 。 


options 脚 本 会 定义 后 续 工 作 将 要 用 到 的 变量 ， 然 后 根据 本 次 参数 以 及 默认 值 设置 这 些 变 量 


. auto/options 


#auto/init 脚 本 初始 化 后 续 将 产生 的 文件 路 径 。 例 如 ， 
Makefile、 
ngx modqules.c 等 文件 默认 情况 下 将 会 在 


<nginx-source>/objs/ 
. auto/init 


#auto/sources 脚 本 将 分 析 
Nginx 的 源码 结构 ， 这 样 才 能 构造 后 续 的 


Makefile 文 件 


. auto/sources 


# 编 译 过 程 中 所 有 目标 文件 生成 的 路 径 由 一 
builddir=DIR 参 数 指定 ， 默 认 情 况 下 为 


<nginx-source>/objs， 此 时 这 个 目录 将 会 被 创建 


test -d SNGX OBJS || mkdir SNGX OBJS 
# 开 始 准备 建立 


ngx auto headers.h.、 
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autoconf .er 等 必要 的 编译 文件 





echo > SNGX AUTO HEADERS H 
echo > SNGX AUTOCONF ERR 
# 向 














objs/ngx auto config.h 写 入 命令 行 带 的 参数 








echo "#define NGX CONFIGURE \"$NGX CONFIGURE\"" > $NGX AUTO CONFIG H 
# 判 断 


[| 


EBUG 标 志 ， 如 果 有 ， 那 么 在 





objs/ngx auto config.h 文 件 中 写 入 











if [ SNGX DEBUG = YES ]; then 
have=NGX DEBUG . auto/have 





fi 
# 现 在 开始 检查 操作 系统 参数 是 否 支持 后 续 编译 


if test -z "$NGX PLATFORM"; then 
echo "checking for OS™" 
NGX SYSTEM= uname -s 2>/dev/null. 
NGX RELEASE= uname -r 2>/dev/null. 
NGX MACHINE= uname -m 2>/dev/null. 
# 屏 幕 上 输出 




















OS 名 称 、 内 核 版 本 、 


32 位 


/64 位 内 核 





echo " + SNGX SYSTEM S$NGX RELEASE SNGX MACHINE" 
NGX PLATFORM="$NGX SYSTEM:SNGX _ RELEASE :SNGX MACHINE" 
Case "SNGX SYSTEM" in 
MINGW32 *) 
NGX PLATFORM=win32 












































esac 

else 
echo "building for $NGX PLATFORM" 
NGX_SYSTEM=$NGX PLATFORM 





fi 
# 检 查 并 设置 编译 器 ， 如 


GCC 是 否 安 装 、 
GCC 版 本 是 否 支 持 后 续 编 译 


nginx 
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# 对 非 


Windows 操 作 系 统 定义 一 些 必要 的 头 文 件 ， 并 检查 其 是 否 存 在 ， 以 此 决定 


configure 后 续 步 骤 是 否 可 以 成 功 


吗 j 

二 在 下 "SNGX PLATFORM" I!= win32 ]; then 
. auto/headers 

fi 


# 对 于 当前 操作 系统 ， 定 义 一 些 特定 的 操作 系统 相关 的 方法 并 检查 当前 环境 是 否 支持 。 例 如 ， 对 于 


Linux， 在 这 里 使 用 


scheqd setaffinity 设 置 进程 优先 级 ， 使 用 


Linux 特 有 的 


sendfile 系 统 调 用 来 加 速 向 网 络 中 发 送 文 件 块 


. auto/os/conf 
# 定 义 类 


UNIX 操作 系统 中 通用 的 头 文件 和 系统 调用 等 ， 并 检查 当前 环境 是 否 支 持 


元 万 下 "SNGX_ PLATFORM" I!= win32 ]; then 
. auto/unix 

fi 

# 最 核心 的 构造 运行 期 


modules 的 脚本 。 它 将 会 生成 


ngx modules.c 文 件 ， 这 个 文件 会 被 编译 进 


Nginx 中 ， 其 中 它 所 做 的 唯一 的 事情 就 是 定义 了 


ngx modules 数 组 。 


ngx moqules 指 明 


Nginx 运 行 期 间 有 哪些 模块 会 参与 到 请 求 的 处 理 中 ， 包 括 


HTTP 请 求 可 能 会 使 用 哪些 模块 处 理 ， 因 此 ， 它 对 数组 元 素 的 顺序 非常 敏感 ， 也 就 是 说 ， 绝 大 部 分 模块 在 





ngx modules 数 组 中 的 顺序 其 实 是 固定 的 。 例 如 ， 一 个 请 求 必 须 先 执行 
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ngx http gzip filter module 模 块 重新 修改 








HTTP 响 应 中 的 头 部 后 ， 才 能 使 用 
ngx_http header _ filter 模块 按照 
headers_in 结 构 体 里 的 成 员 构 造 出 以 

TCP 流 形式 发 送 给 客户 端的 

HTTP 响 应 头 部 。 注 意 ， 我 们 在 
--add-module= 参 数 里 加 入 的 第 三 方 模块 也 在 此 步 又 写 入 到 


ngx rmodules.c 文 件 中 了 


auto/modules 


#conf 脚 本 用 来 检查 


Nginx 在 链接 期 间 需 要 链接 的 第 三 方 静态 库 、 动 态 库 或 者 目标 文件 是 否 存 在 


. auto/lib/conf 
# 处 理 


Nginx 安 装 后 的 路 径 


case ".$NGX PREFIX" in 
.) 








NGX PREFIX=$ {NGX PREFIX:-/usr/local/nginx} 
have=NGX PREFIX value="\"$NGX PREFIX/\"" . auto/define 











NGX PREFIX= 

















have=NGX PREFIX value="\"$NGX PREFIX/\"" . auto/define 

esac 
# 处 理 
Nginx 安 装 后 
conf 文 件 的 路 径 
if [ ".$NGX CONF PREFIX" != "." ]; then 

have=NGX CONF PREFIX value="\"$NGX CONF PREFIX/\"" . auto/define 
二 
# 处 理 


Nginx 安 装 后 ， 二 进 制 文件 、 
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lock 等 其 他 文件 的 路 径 可 参见 


configure 参 数 中 路 径 类 选项 的 说 明 


have=NGX_ SBIN PATH value="\"$NGX SBIN PATH\"" . auto/define 
have=NGX CONF PATH value="\"$NGX CONF PATH\"" . auto/define 
have=NGX PID PATH value="\"$NGX PID PATH\"" . auto/define 
have=NGX LOCK PATH value="\"$NGX LOCK PATH\"" . auto/define 
have=NGX ERROR LOG PATH value="\"$NGX ERROR LOG PATH\"" . auto/define 
have=NGX HTTP LOG PATH value="\"$NGX HTTP LOG PATH\"" . auto/define 

have=NGX HTTP CLIENT TEMP PATH value="\"$NGX HTTP CLIENT TEMP PATH\"" . auto/define 
have=NGX HTTP PROXY TEMP PATH value="\"$NGX HTTP PROXY TEMP PATH\"" . auto/define 


have=NGX HTTP FASTCGI TEMP PATH value="\"$NGX HTTP FASTCGI TEMP PATH\"" . auto/define 



























































have=NCX HTTP UWSGI TEMP PATH value="\"$NGX HTTP UWSGI TEMP PATH\"" . auto/define 
have=NGX HTTP SCGI TEMP PATH value="\"$NGX HTTP SCGI TEMP PATH\"" . auto/define 
# 创 建 编译 时 使 用 的 










































































objs/Makefile 文 件 


auto/make 


# 为 


objs/Makefile 加 入 需要 连接 的 第 三 方 静态 库 、 动 态 库 或 者 目标 文件 


auto/lib/make 
# 为 


objs/Makefile 和 加 入 
install 功 能 ， 当 执行 


make install 时 将 编译 生成 的 必要 文件 复制 到 安装 路 径 ， 建 立 必 要 的 目录 


. auto/install 
# 在 
ngx auto config.h 文 件 中 加 入 


NGX _SUPPRESS_ WARN 宏 、 





NGX_SMP 安 


auto/stubs 


# 在 


ngx_ auto config.h 文 件 中 指定 





NGX_USER 和 
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configure 时 没有 参数 指定 ， 默 认 两 者 臂 为 


nobody (也 就 是 默认 以 


nobody 用 户 运 行进 程 ) 








have=NGX USER value="\"$NGX USER\"" . auto/define 
have=NGX GROUP value="\"$NGX GROUP\"" . auto/define 
# 显 示 


configure 执 行 的 结果 ， 如 果 失 败 ， 则 给 出 原因 





. auto/summary 





( 注 : 在 conf igutre 脚 本 里 检查 菜 个 特性 是 否 存 在 时 ， 会 生成 一 个 最 简单 的 只 包含 main 函 数 的 C 程 序 ， 该 程序 会 包含 和 


1.5.3 configure 生 成 的 文件 








当 configure 执 行 成 功 时 会 生成 objs 目 录 ， 并 在 该 目录 下 产生 以 下 目录 和 文件 : 





---ngx_auto headers.h 
-=--autoconf ,err 
-——ngx auto config.h 
---ngx modules.c 
-BXG 
= 一 SG 
= 一 人 VEGI 七 
1---modules 
二 CS 
|---unix 
|---win32 
---http 
|---modules 
| |===perl 
= 
~ 
---Makefile 











上 述 目录 和 文件 介绍 如 下 。 

















1) src 目 录用 于 存放 编译 时 产生 的 目标 文件 。 
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2) Makefile 文 件 用 于 编译 Nginx 工 程 以 及 在 加 入 install 参 数 后 安装 Nginx。 


3) autoconf.err 保 存 configure 执 行 过 程 中 产生 的 结果 。 


4) ngx_auto_headers.h 和 和 ngx_ auto_config.h 保 存 了 一 些 宏 ， 这 两 个 涉 文 件 会 被 sre/core/mgx_config.h 及 src/os/unix/ngx_linu 


5) ngx_modules.c 是 一 个 关键 文件 ， 我 们 


#include <ngx config.h> 


#include <ngx core.h>**: 


ngx module t *ngx modules[] = { 


&ngx_core module, 

&ngx errlog module, 
&ngx_ conf module, 

&ngx events module, 
&ngx event core module, 
&ngx epoll module, 


&ngx http module, 
&ngx http core module, 


&ngx http log module, 
&ngx http upstream module, 
&ngx http static module, 


&ngx http autoindex module, 


&ngx http index module, 
&ngx http auth basic module, 
&ngX htt 
&ngX htt 2 
&ngx http limit req module, 
&ngX htt 1 
&ngx http map module, 

&ngx http split clients module, 
&ngX htt 
&ngx htt 
&ngX htt 
&ngx htt 
&ngX htt 
&nGX htt 
&ngX htt | 1 

&ngx http empty gif module, 


&ngx http browser module, 


&ngx http upstream ip hash module, 
&ngx http write filter module, 

&ngx http header filter module, 

&ngx http chunked filter module, 

&ngx http range header filter module, 
&ngx http gzip filter module, 

&ngx http postpone filter module, 
&ngx http ssi filter module, 

&ngx http charset filter module, 
&ngx http userid filter module, 

&ngx http headers filter module, 

&ngx http copy filter module, 

&ngx http range body filter module, 
&ngx http not modified filter module, 
NULL 
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需要 


看 看 它 的 内 部 结构 。 一 个 默认 配置 下 生成 的 ngx_modules.c 文 件 内 容 如 下 








ngx_modules.c 文 件 就 是 用 来 定义 ngx_modules 数 组 的 。 





ngx_modules 是 非常 关键 的 数组 ， 它 指明 了 每 个 模块 在 Nginx 中 的 优先 级 ， 当 一 个 请 求 同 时 符合 多 个 模块 的 处 理 规则 F 
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是 auto/modules 脚 本 执行 后 E 





SL 


这 





的 顺序 会 导致 Nginx 无 法 工作 ， 

















因此 ，ngx_modules 中 模块 的 先后 顺序 非常 重要 ， 不 正确 





。 Configu: 











可 以 看 出 ， 在 安装 过 程 中 ，configure 做 了 大 量 的 幕后 工作 ， 我 们 需要 关注 在 这 个 过 程 中 Nginx 做 了 哪些 事情 











FE 成 了 ngx_modules.c 文 件 ， 它 决定 了 运行 时 所 有 模块 的 优先 级 在 编译 过 程 中 而 不 





configure 除 了 生成 Makefile 外 ， 还 4 


时 AL 


最 简单 的 只 包含 main 函 数 的 C 程 序 ， 该 程序 会 包含 相应 的 头 文人 


[1] 
在 configute 脚 本 里 检查 某 个 特性 是 否 存 在 时 ， 会 生成 一 个 
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1.6 Nginx 的 命令 行 控制 


在 Linux 中 ， 需 要 使 用 命令 行 来 控制 Nginx 服 务 器 的 启动 与 停止 、 重 载 配置 文件 、 回 滚 日 
志文 件 、 平 滑 升级 等 行为 。 默 认 情 况 下 ，Nginx 被 安装 在 目录 usrlocal/nginx/ 中 ， 其 二 进 制 文 
件 路 径 为 usrlocal/nginc/sbin/nginx， 配 置 文件 路 径 为 usrlocal/nginx/conf/nginx.conf。 当 然 ， 在 
configure 执 行 时 是 可 以 指定 把 它们 安装 在 不 同 目录 的 。 为 了 简单 起 见 ， 本 节 只 说 明 默 认 安 装 
情况 下 的 命令 行 的 使 用 情况 ， 如 果 读 者 安装 的 目录 发 生 了 变化 ， 那 么 蔡 换 一 下 即 可 。 





(1) 默认 方式 启动 

直接 执行 Nginx 二 进 制程 序 。 例 如 : 
ee i 

这 时 ， 会 读 取 默认 路 径 下 的 配置 文件 : usrlocal/nginx/conf/nginx.conf。 


实际 上 ， 在 没有 显 式 指定 nginx.conf 配 置 文件 路 径 时 ， 将 打开 在 configure 命 令 执 行 时 使 用 - 


-confpath=PATH 指 定 的 nginx.conf 文 件 〈 参 见 1.5.1 节 ) 。 
(2) 另行 指定 配置 文件 的 启动 方式 
使 用 -c 参 数 指定 配置 文件 。 例 如 : 
RE 


这 时 ， 会 读 取 -c 参 数 后 指定 的 nginx.conf 配 置 文件 来 局 动 Nginx。 





(3) 男 行 指定 安装 目录 的 局 动 方式 


使 用 -p 参 数 指定 Nginx 的 安装 目录 。 例 如 : 
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usrlocal/nginx/sbin/nginx -p usrlocal/nginx/ 





(4) 男 行 指定 全 局 配置 项 的 局 动 方式 


可 以 通过 -g 参 数 临 时 指定 一 些 全 局 配置 项 ， 以 使 新 的 配置 项 生效 。 例 如 : 





usrlocal/nginx/sbin/nginx -g "pid varnginx/test.pid;" 








上 面 这 行 命令 意味 着 会 把 pid 文 件 写 到 varnginx/test.pid 中 。 


-g 参 数 的 约束 条 件 是 指定 的 配置 项 不 能 与 默认 路 径 下 的 nginx.conf 中 的 配置 项 相 冲 突 ， 否 
则 无 法 启动 。 束 像 上 例 那 样 ， 类 似 这 样 的 配置 项 :pid logs/nginx.pid， 是 不 能 存在 于 默认 的 
nginx.conf 中 的 。 


男 一 个 约束 条 件 是 ， 以 -g 方 式 启动 的 Nginx 服 务 执行 其 他 命令 行 时 ， 需 要 把 -g 参 数 也 带 
否则 可 能 出 现 配置 项 不 匹配 的 情形 。 例 如 ， 如 果 要 停止 Nginx 服 务 ， 那 么 需要 执行 下 面 
代码 : 











usrlocal/nginx/sbin/nginx -9 "pid varnginx/test.pid;" -s stop 





如 果 不 带 上 -g"'pidvarnginx/test.pid;"， 那 么 找 不 到 pid 文 件 ， 也 会 出 现 无 法 停止 服务 的 情 
况 。 








(5) 测试 配置 信息 是 否 有 错误 








在 不 局 动 Nginx 的 情况 下 ， 使 用 -t 参 数 仅 测 试 配置 文件 是 否 有 和 错误。 例如 : 





usrlocal/nginx/sbin/nginx -t 








执行 结果 中 显示 配置 是 否 正 确 。 
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测试 配置 选项 时 ， 使 用 -q 参 数 可 以 不 把 error 级 别 以 下 的 信息 输出 到 屏幕 。 例 如 : 





usrlocal/nginx/sbin/nginx -七 -q 








(7) 显示 版 本 信息 


使 用 -v 参 数 显 示 Nginx 的 版 本 信息 。 例 如 : 





usrlocal/nginx/sbin/nginx -Vv 





(8) 显示 编译 阶段 的 参数 





使 用 -V 参 数 除了 可 以 显示 Nginx 的 版 本 信息 外 ， 还 可 以 显示 配置 编译 阶段 的 信息 ， 如 
GCC 编 译 器 的 版 本 、 操 作 系 统 的 版 本 、 执 行 configure 时 的 参数 等 。 例 如 : 





usrlocal/nginx/sbin/nginx -V 





(9) 快速 地 停止 服务 








使 用 -s stop 可 以 强制 停止 Nginx 服 务 。-s 参 数 其 实 是 告诉 Nginx 程 序 同 正 在 运行 的 Nginx 服 
务 发 送信 号 量 ，Nginx 程 序 通过 nginx.pid 文 件 中 得 到 master 进 程 的 进程 ID， 再 癌 运 行 中 的 
master 进 程 发 送 TERM 信 号 来 快速 地 关闭 Nginx 服 务 。 例 如 : 





usrlocal/nginx/sbin/nginx -s stop 





实际 上 ， 如 果 通 过 kill 命 令 直 接 向 nginx master 进 程 发 送 TERM 或 者 INT 人 信号， 效果 是 一 样 
的 。 例 如 ， 先 通过 ps 命令 来 得 看 nginx master 的 进程 ID: 





:anhf5wapi001:root > ps -ef | grep nginx 
root 10800 1 0 02:27 ? 00:00:00 nginx: master process ./nginx 
root 10801 10800 0 02:27 ? 00:00:00 nginx: worker process 
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接 下 来 直接 通过 kill 命令 来 发 送信 和 号 : 





kill -s SIGTERM 10800 





或 者 : 


kill -s SIGINT 10800 





上 述 两 条 命令 的 效果 与 执行 wsrlocal/nginx/sbin/nginx-s stop 是 完全 一 样 的 。 
(10)“ 优 雅 ” 地 停止 服务 


如 末 布 望 Nginx 服 务 可 以 正常 地 处 理 完 当 前 所 有 请 求 再 集 止 服务 ， 那 么 可 以 使 用 -s quit 参 
数 来 停止 服务 。 例 如 : 


usrlocal/nginx/sbin/nginx -s quit 


该 命令 与 快速 停止 Nginx 服 务 是 有 区 别 的 。 当 快速 停止 服务 时 ，worker 进 程 与 master 进 程 
在 收 到 信号 后 会 立刻 跳出 循环 ， 退 出 进程 。 而 “优雅 ”地 停止 服务 时 ， 首 先 会 关闭 监听 端口 ， 
停止 接收 新 的 连接 ， 然 后 把 当前 正在 处 理 的 连接 全 部 处 理 完 ， 最 后 再 退出 进程 。 


与 快速 停止 服务 相似 ， 可 以 直接 发 送 QUIT 信 号 给 master 进 程 来 停止 服务 ， 其 效果 与 执 
行 -s quit 命 令 是 一 样 的 。 例 如 : 


kill -s SIGQOUIT <nginx master pid> 





如 果 而 望 “优雅 "地 停止 茶 个 worker 进 程 ， 那 么 可 以 通过 回访 进程 发 送 WINCH 信 号 来 停止 
服务 。 例 如 : 


kill -s SIGWINCH <nginx worker pid> 
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(11) 使 运行 中 的 Nginx 重 读 配 置 项 并 生效 
使 用 -s reload 参 数 可 以 使 运行 中 的 Nginx 服 务 重 新 加 载 nginx.conf 文 件 。 例 如 : 


usrlocal/nginx/sbin/nginx -s reload 


事实 上 ，Nginx 会 先 检查 新 的 配置 项 是 否 有 误 ， 如 采 全 部 正确 就 以 “优雅 ”的 方式 关闭 ， 
再 重新 局 动 Nginx 来 实现 这 个 目的 。 类 似 的 ，-s 是 发 送信 号 ， 仍 然 可 以 用 kill 命令 发 送 HUP 信 
号 来 达到 相同 的 效果 。 


kill -s SIGHUP <nginx master pid> 
(12) 日 志文 件 回 滚 


使 用 -s reopen 参 数 可 以 重新 打开 日 志文 件 ， 这 样 可 以 先 把 当前 日 志文 件 改 名 或 转移 到 其 
他 目录 中 进行 备份 ， 再 重新 打开 时 就 会 生成 新 的 日 志文 件 。 这 个 功能 使 得 日 志文 件 不 至 于 过 
大 。 例 如 : 


usrlocal/nginx/sbin/nginx -s reopen 

当然 ， 这 与 使 用 Kill1 命 令 发 送 USR1 信 号 效果 相同 。 
Ei de et ld 

(13) 平滑 升级 Nginx 


当 Nginx 服 务 升级 到 新 的 版 本 时 ， 必 须要 将 旧 的 二 进 制 文件 Nginx 蔡 换 掉 ， 通 常情 况 下 这 
古 需 要 重启 服务 的 ， 但 Nginx 文 持 不 重 局 服务 来 完成 新 版 本 的 平滑 升级 。 


升级 时 包括 以 下 步 又: 


于 和 开 各 于 训 SP2 信 号 二 BA 








的 。 例 如 : 





kill -s SIGUSR2 <nginx master pid> 


这 时 ， 运 行 中 的 Nginx 会 将 pid 文 件 重 命名 ， 如 将 usrlocal/nginx/logs/nginx.pid 香 命名 
为 usrlocal/nginx/logs/nginx.pid.oldbin， 这 样 新 的 Nginx 才 有 可 能 启动 成 功 。 


2) 启动 新 版 本 的 Nginx， 可 以 使 用 以 上 介绍 过 的 任意 一 种 启动 方法 。 这 时 通过 ps 命令 可 
以 发 现 新 旧版 本 的 Nginx 在 同时 运行 


3) 通过 kill 命令 向 旧版 本 的 master 进 程 发 送 SIGQUIT 信 和 号， 以 “优雅 ”的 方式 关闭 旧版 本 的 
Nsginx。 随 后 将 只 有 新 版 本 的 Nginx 服 务 运 行 ， 此 时 平滑 升级 完毕 





使 用 -h 或 者 -? 参 数 会 显示 文 持 的 所 有 命令 行 参数 。 
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tL 才 必 


本 章 介 绍 了 Nginx 的 特点 以 及 在 什么 场景 下 需要 使 用 Nginx， 同 时 介绍 了 如 何 获取 Nginx 以 
及 如 何 配置 、 编 译 、 安 装运 行 Nginx。 本 章 还 深入 介绍 了 最 为 复杂 的 configure 过 程 ， 这 部 分 内 


容 是 学 习 本 书 第 二 部 分 和 第 三 部 分 的 基础 。 


节 
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第 2 瘟 ”Neginx 的 配置 














Nginx 拥 有 大 量 官方 发 布 的 模块 和 第 三 方 模块 ， 这 些 已 有 的 模块 可 以 帮助 我 们 实现 Web 服 
务 器 上 很 多 的 功能 。 使 用 这 些 模块 时 ， 仅 仅 需 要 增加 、 修 改 一 些 配置 项 即 可 。 因 此 ， 本 章 的 
目的 是 熟悉 Nginx 的 配置 文件 ， 包 括 配置 文件 的 语法 格式 、 运 行 所 有 Nginx 服 务必 须 具 备 的 基 
础 配置 以 及 使 用 HTTP 核 心 模块 配置 静态 Web 服 务 器 的 方法 ， 最 后 还 会 介绍 反 辐 代理 服务 


已 局 


了 To 





通过 本 章 的 学 习 ， 读 者 可 以 : 玖 练 地 配置 一 个 静态 Web 服 务 器 ， 对 影响 Web 服 务 亏 性 能 
的 各 个 配置 项 有 深入 的 理解 ， 对 配置 语法 有 全 面 的 了 解 。 通 过 互联 网 或 其 他 途径 得 到 任意 模 
块 的 配置 说 明 ， 然 后 可 通过 修改 nginx.conf 文 件 来 使 用 这 些 模块 的 功能 。 
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2.1 运行 中 的 Nginx 进 程 间 的 关系 


在 正式 提供 服务 的 产品 环境 下 ， 部 署 Nginx 时 都 是 使 用 一 个 master 进 程 来 管理 多 个 worker 
进程 ， 一 般 情况 下 ，worker 进 程 的 数量 与 服务 器 上 的 CPU 核 心 数 相等 。 每 一 个 worker 进 程 都 
是 繁忙 的 ， 它 们 在 真正 地 提供 互联 网 服务 ，master 进 程 则 很 “清闲 *?"， 只 负责 监控 管理 worker 
进程 。worker 进 程 之 间 通 过 共享 内 存 、 原 子 操作 等 一 些 进程 间 通 信 机 制 来 实现 负载 均衡 等 功 
能 《第 9 章 将 会 介绍 负载 均衡 机 制 ， 第 14 章 将 会 介绍 负载 均衡 锁 的 实现 ) 。 








部 署 后 Nginx 进 程 间 的 关系 如 图 2-1 所 示 。 


Nginx 是 文 持 单 进程 《master 进 程 ) 提供 服务 的 ， 那 么 为 什么 产品 环境 下 要 按照 master- 
worker 方 式 配置 同时 局 动 多 个 进程 昵 ? 这 样 做 的 好 处 主要 有 以 下 两 点 


. 由 于 master 进 程 不 会 对 用 户 请 求 提 供 服务 ， 只 用 于 管理 真正 提供 服务 的 worker 进 程 ， 
所 以 mastet 进 程 可 以 是 唯一 的 ， 它 仅 专 注 于 自己 的 纯 管理 工作 ， 为 管理 员 提 供 命令 行 服务 ， 
包括 诸如 启动 服务 、 停 止 服务 、 重 载 配置 文件 、 平 滑 升级 程序 等 。mastef 进 程 需 要 拥有 较 大 
的 权限 ， 例 如 ， 通 常会 利用 toot 用 户 启动 mastef 进 程 。wotket 进 程 的 权限 要 小 于 或 等 于 mastet 
进程 ， 这 样 mastef 进 程 才 可 以 完全 地 管理 wotket 进 程 。 当 任意 一 个 wotker 进 程 出 现 错误 从 而 导 


致 coredump 时 ，master 进 程 会 立刻 启动 新 的 worket 进 程 继 续 服 务 。 


之 


* 多 个 worket 进 程 处 理 互 联网 请 求 不 但 可 以 提高 服务 的 健壮 性 (一 个 worker 进 程 出错 
后 ， 其 他 worker 进 程 仍然 可 以 正常 提供 服务 ) ， 最 重要 的 是 ， 这 样 可 以 充分 利用 现在 常 
SMP 多 核 架 构 ， 从 而 实现 微观 上 真正 的 多 核 并 发 处 理 。 因 此 ， 用 一 个 进程 (master 进 程 ) 来 
处 理 互联 网 请 求 肯定 是 不 合适 的 。 另 外 ， 为 什么 要 把 worketr 进 程 数量 设置 得 与 CPU 核 心 数量 
一 致 呢 ? 这 正 是 Nginx 与 Apache 服 务 器 的 不 同 之 处 。 在 Apache 上 每 个 进程 在 一 个 时 刻 只 处 理 
一 个 请 求 ， 因 此 ， 如 果 硕 望 Web 服 务 器 拥有 并 发 处 理 的 请 求 数 更 多 ， 就 要 把 Apache 的 进程 或 


线程 数 设 通常 会 达到 一 台 服 务 器 拥有 几 百 个 工作 进程 ， 这 样 大 量 的 进程 间 切 换 将 
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带 来 无 谓 的 系统 资源 消耗 。 而 Nginx 则 不 然 ， 一 个 wotket 进 程 可 以 同时 处 理 的 请 求 数 只 受 限 于 
内 存 大 小 ， 而 且 在 架构 设计 上 ， 不同 的 worket 进 程 之 间 处 理 并 发 请 求 时 几乎 没有 同步 锁 的 限 
制 ，worket 进 程 通常 不 会 进入 睡眠 状态 ， 因 此 ， 当 Nginx 上 的 进程 数 与 CPU 核 心 数 相 等 时 (最 


好 每 一 个 wofker 进 程 都 绑 定 特定 的 CPU 核心 ) ， 进 程 间 切 换 的 代价 是 最 小 的 。 
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图 2-1 部 署 后 Nginx 进 程 间 的 关系 








举例 来 说 ， 如 果 产 品 中 的 服务 器 CPU 核 心 数 为 8， 那 么 就 需要 配置 8 个 worker 进 程 ( 见 图 
2-2) 。 
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图 2-2 ”worker 进 程 的 数量 尽量 与 CPU 核 心 数 相等 


如 果 对 路 径 部 分 都 使 用 默认 配置 ， 那 么 Nginx 运 行 目 录 为 /ust/local/nginx， 其 日 录 结 构 如 
Fs 





---Ssbin 

-一 -nginX 

==~=Gon 

-一 -Koi-win 

——-kKoi-utf 

—---win-utf 

---mime .types 
---mime.types.default 
---fastcgi params 
---fastcgi params.default 
---fastcgi.conf 
---fastcgi.conf.default 
---uwsgi params 
---uwsgi params.default 
---Sscgi params 

---Scgi params.default 
===Nnginx.Conf 
---nginx.conf.default 
===]OgSs 

le 

---access .1og 
---nginx.pid 

===html 

===D0xEmL 
---index.html 
---client body temp 

-一 -PEOXY temp 
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---uwsgi temp 
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2.2 Nginx 配 置 的 通用 语法 


Nginx 的 配置 文件 其 实 是 一 个 普通 的 文本 文件 。 下 面 来 看 一 个 简单 的 例子 。 





user nobody; 
worker processes 8; 
error log varlog/nginx/error.log error; 
#pid logs/nginx.pid; 
events { 
use epoll; 
worker connections 50000; 
} 
http { 
include mime.types; 
default type application/octet-stream; 
log format main '$remote addr [$time local] "$request" ' 
'$status $bytes sent "S$http referer™ ' 
'"$http user agent" "S$http x forwarded for"'; 
access log logs/access.log main buffer=32k; 





在 这 段 简短 的 配置 代码 中 ， 每 一 行 配置 项 的 语法 格式 都 将 在 2.2.2 节 介绍 ， 出 现 的 events 
和 http 块 配置 项 将 在 2.2.1 节 介绍 ， 以 # 符 号 开头 的 注释 将 在 2.2.3 节 介绍 ， 类 似 “buffer=32k”* 这 
样 的 配置 项 的 单位 将 在 2.2.4 节 介绍 。 


2.2.1 块 配 置 项 


块 配置 项 由 一 个 块 配 置 项 名 和 一 对 大 括号 组 成 。 具 体 示例 如 下 : 





events ({… 


} 
http: 4 
upstream backend { 
server 127.0.0.1:8080; 
} 
gzip on; 
server { 
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location /webstatic 1{ 
ZL Off 
} 


上 面 代 码 段 中 的 events、http、server、location、upstream 等 都 是 块 配置 项 ， 块 配置 项 之 
后 是 否 如 “location/webstatic{.….}” 那 样 在 后 面 加 上 参数 ， 取 决 于 解析 这 个 块 配 置 项 的 模块 ， 不 
能 一 概 而 论 ， 但 块 配置 项 一 定 会 用 大 括号 把 一 系列 所 属 的 配置 项 全 包含 进来 ， 表 示 大 括号 内 
的 配置 项 同时 生效 。 所 有 的 事件 类 配置 都 要 在 events 块 中 ，http、server 等 配置 也 遵循 这 个 规 


me 


自 。 


块 配置 项 可 以 藤 套 。 内 层 块 直接 继承 外 层 块 ， 例 如 ， 上 例 中 ，server 块 里 的 任意 配置 都 
是 基于 http 块 里 的 已 有 配置 的 。 当 内 外 层 块 中 的 配置 发 生 冲 突 时 ， 究 竟 是 以 内 层 块 还 是 外 层 
块 的 配置 为 准 ， 取 决 于 解析 这 个 配置 项 的 模块 ， 第 4 章 将 会 介绍 http 块 内 配置 项 冲突 的 处 理 方 
法 。 例 如 ， 上 例 在 http 模 块 中 己 经 打开 了 “gzip on;:*"， 但 其 下 的 location/webstatic 又 把 gzip 关 闭 
了 : gzip off， 最 终 ， 在 /webstatic 的 处 理 模块 中 ，gzip 模 块 是 按照 gzip of 来 处 理 请 求 的 。 





2.2.2 配置 项 的 语法 格式 


从 上 文 的 示例 可 以 看 出 ， 最 基本 的 配置 项 语法 格式 如 下 : 


配置 项 名 
配置 项 值 
1 配置 项 值 





下 面 解释 一 下 配置 项 的 构成 部 分 。 


和 在 生 区 可 时 枯 各 ， 玫 上 时 和 和 曙光 年 一人 起 才 天 昌浩 











则 Nginx 会 认为 配置 文件 出 现 了 非法 的 配置 项 名 。 配 置 项 名 输入 结束 后 ， 将 以 空格 作为 分 隔 


Ar 


符 。 





其 次 是 配置 项 值 ， 它 可 以 是 数字 或 字符 串 (当然 也 包括 正则 表达 式 ) 。 针 对 一 个 配置 
项 ， 既 可 以 只 有 一 个 值 ， 也 可 以 包含 多 个 值 ， 配 置 项 值 之 间 仍 然 由 空格 符 来 分 隔 。 当 然 ， 一 
个 配置 项 对 应 的 值 究 竟 有 多 少 个 ， 取 决 于 解析 这 个 配置 项 的 模块 。 我 们 必须 根据 菜 个 Nginx 
模块 对 一 个 配置 项 的 约定 来 更 改 配 置 项 ， 第 4 章 将 会 介绍 模块 是 如 何 约定 一 个 配置 项 的 格 
了 











最 后 ， 每 行 配置 的 结尾 需要 加 上 分 号 。 


@ i 如 果 配 置 项 值 中 包括 语法 符号 ， 比 如 空格 符 ， 那 么 需要 使 用 单 引 号 或 双 引 号 


括 住 配置 项 值 ， 否 则 Nginx 会 报 语法 错误 。 例 如 : 





log format main "Sremote addr - S$remote user [$time local] "$request™" '; 





2.2.3 配置 项 的 注释 


如 果 有 一 个 配置 项 暂时 需要 注释 挥 ， 那 么 可 以 加 “#” 注 释 掉 这 一 行 配置 。 例 如 : 





#pid logs/nginx.pid; 





2.2.4 配置 项 的 单位 





大 部 分 模块 遵循 一 些 通用 的 规定 ， 如 指定 空间 大 小 时 不 用 每 次 都 定义 到 字 市 、 指 定时 间 
时 不 用 精确 到 毫秒 。 


当 指 定 空间 大 小 时 ， 可 以 使 用 的 单位 包括 : 
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. 区 或 者 Kk 千 字 节 (KiloByte，KB) 。 
. M 或 者 m 兆 字 节 (MegaByte, MB) 。 


例如 : 





gzip buffers 4 8k; 
client max body size 64M; 





当 指 定时 间 时 ， 可 以 使 用 的 单位 包括 : 


ms 〈 毫 秒 ) ，s( 秒 ) ，m (分 钟 ) ，h (小 时 ) , d (天 ) , w ( 周 ， 包 含 7 天 ) ， 
M (月 ， 包 含 30 天 ) ，y (年 ， 包 含 365 天 ) 。 





例如 : 
expires 10y; 
proxy read timeout 600; 
client body timeout 2m; 





@ 注意 ”配置 项 后 的 值 究 竞 是否 可 以 使 用 这 些 单位 ， 取 决 于 解析 该 配置 项 的 模块 。 如 
果 这 个 模块 使 用 了 Nginx 框 架 提 供 的 相应 解析 配置 项 方法 ， 那 么 配置 项 值 才 可 以 携带 单位 。 
第 4 章 中 详细 描述 了 Nginx 框 架 提供 的 14 种 预 设 解析 方法 ， 其 中 一 些 方法 将 可 以 解析 以 上 列 出 
的 单位 。 


2.2.5 在 配置 中 使 用 变量 





有 些 模 块 允 许 在 配置 项 中 使 用 变量 ， 如 在 日 志 记录 部 分 ， 有 具体 示例 如 下 。 





log format main "Sremote addr - S$remote user [$time local] "$request" ' 
1$status $bytes sent "S$http referer™ ' 
'"$http user agent" "S$http x forwarded for"'; 











其 和 i 向 ey cbr 这 种 





变量 只 有 少数 模块 支持 ， 并 不 是 通用 的 。 


许多 模块 在 解析 请 求 时 都 会 提供 多 个 变量 (如 本 章 后 面 提 到 的 http core module、http 
proxy module、http upstream module 等 ) ， 以 使 其 他 模块 的 配置 可 以 即时 使 用 。 我 们 在 学 习 某 
个 模块 提供 的 配置 说 明 时 可 以 关注 它 是 否 提供 变量 。 


SO 提示 。 在 执行 configute 命 令 时 ， 我 们 已 经 把 许多 模块 编译 进 Nginx 中 ， 但 是 否 启 用 这 
些 模 块 ， 一 般 取 决 于 配置 文件 中 相应 的 配置 项 。 换 和 句 话 说 ， 每 个 Nginx 模 块 都 有 自己 感 兴趣 
的 配置 项 ， 大 部 分 模块 都 必须 在 nginx.conf 中 读 取 某 个 配置 项 后 才 会 在 运行 时 局 用 。 例 如， 只 
有 当 配 置 http{...} 这 个 配置 项 时 ，ngx_http_module 模 块 才 会 在 Nginx 中 启用 ， 其 他 依赖 
ngx_http_module 的 模块 也 才能 正常 使 用 。 
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2.3 Nginx 服 务 的 基本 配置 
Nginx 在 运行 时 ， 至 少 必 须 加 载 几 个 核心 模块 和 一 个 事件 类 模块 。 这 些 模块 运行 时 所 支 
持 的 配置 项 称 为 基本 配置 所 有 其 他 模块 执行 时 都 依赖 的 配置 项 。 


下 面 详 述 基本 配置 项 的 用 法 。 由 于 配置 项 较 多 ， 所 以 把 它们 按照 用 户 使 用 时 的 预期 功能 
分 成 了 以 下 4 类 : 


用 于 调试 、 定 位 问题 的 配置 项 。 
` 正常 运行 的 必 备 配置 项 。 
优化 性 能 的 配置 项 。 


" 事件 类 配置 项 (有些 事 件 类 配置 项 归纳 到 优化 性 能 类 ， 这 是 因为 它们 虽然 也 属于 
events{} 块 ， 但 作用 是 优化 性 能 ) 。 
有 这 么 一 些 配 置 项 ， 即 使 没有 显 式 地 进行 配置 ， 它 们 也 会 有 默认 的 值 ， 如 daemon， 即 使 


在 nginx.conf 中 没有 对 它 进行 配置 ， 也 相当 于 打开 了 这 个 功能 ， 这 点 需要 注意 。 对 于 这 样 的 配 
置 项 ， 作 者 会 在 下 面相 应 的 配置 项 描述 上 加 入 一 行 “ 默 认 : ”来 进行 说 明 。 





2.3.1 用 于 调试 进程 和 定位 问题 的 配置 项 


先 来 看 一 下 用 于 调试 进程 、 定 位 问题 的 配置 项 ， 如 下 所 示 。 





(1) 是 否 以 守护 进程 方式 运行 Nginx 


语法 : daemon onloff 
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守护 进程 (daemon)〉 是 脱离 终端 并 且 在 后 台 运 行 的 进程 。 它 脱离 终端 是 为 了 避免 进程 执 
行 过 程 中 的 信息 在 任何 终端 上 显示 ， 这 样 一 来 ， 进 程 也 不 会 被 任何 终端 所 产生 的 信息 所 打 
汤 。Nginx 坚 无 疑问 是 一 个 需要 以 守护 进程 方式 运行 的 服务 ， 因 此 ， 默 认 虱 是 以 这 种 方式 运 
行 的 。 











不 过 Nginx 还 是 提供 了 关闭 守护 进程 的 模式 ， 之 所 以 提供 这 种 模式 ， 是 为 了 方便 跟踪 调 
试 Nginx， 毕 葛 用 gdb 调 试 进程 时 最 烦琐 的 就 是 如 何 继续 跟 进 fork 出 的 子 进程 了 。 这 在 第 三 部 
分 研究 Nginx 架 构 时 很 有 用 。 


(2) 是 否 以 master/worker 方 式 工 作 
语法 : master process onloff 


默认 : master process on; 








可 以 看 到 ， 在 如 图 2-1 所 示 的 产品 环境 中 ， 是 以 一 个 master 进 程 管理 多 个 worker 进 程 的 方 
式 运 行 的 ， 几 乎 所 有 的 产品 环境 下 ，Nginx 都 以 这 种 方式 工作 。 


与 daemon 配 置 相同 ， 提 供 master process 配 置 也 是 为 了 方便 跟踪 调试 Neginx。 如 果 用 off 关 
闭 了 master process 方 式 ， 就 不 会 fork 出 worker 子 进程 来 处 理 请 求 ， 而 是 用 master 进 程 自身 来 
处 理 请 求 。 


(3) error 日 志 的 设置 
语法 : error logpathfile level; 


默认 : error log logs/error.log error; 








error 日 志 是 定位 Nginx 问 题 的 最 佳 工具 ， 我 们 可 以 根据 自己 的 需求 妥善 设置 error 日 志 的 
路 径 和 级 别 。 
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pathfile 参 数 可 以 是 一 个 具体 的 文件 ， 例 如 ， 默 认 情况 下 是 logs/error.log 文 件 ， 最 好 将 它 
放 到 一 个 磁盘 空间 足够 大 的 位 置 ，pathfile 也 可 以 是 /dev/null， 这 样 就 不 会 输出 任何 日 志 了 ， 
这 也 是 关闭 error 日 志 的 唯一 手段 ，patpfile 也 可 以 是 stderr， 这 样 日 志 会 输出 到 标准 错误 文件 
中 。 


level 是 日 志 的 输出 级 别 ， 取 值 范围 是 debug、info、notice、warn、error、crit、alert、 
emerg， 从 左 至 右 级 别 依次 增 大 。 当 设 定 为 一 个 级 别 时 ， 大 于 或 等 于 该 级 别 的 日 志 都 会 被 输 
出 到 pathfile 文 件 中 ， 小 于 该 级 别 的 日 志 则 不 会 输出 。 例 如 ， 当 设 定 为 error 级 别 时 ，error、 


crit、alert、emerg 级 别 的 日 志 都 会 输出 。 





如 果 设 定 的 日 志 级 别 是 debug， 则 会 输出 所 有 的 日 志 ， 这 样 数据 量 会 很 大 ， 需 要 预先 确 
保 patpfile 所 在 磁盘 有 足够 的 磁盘 空间 。 


@ 注意 ”如果 日 志 级 别 设 定 到 debug， 必 须 在 configure 时 加 入 --with-debug 配 置 项 。 
(4) 是 否 处 理 几 个 特殊 的 调试 点 
语法 : debug points[stoplabort] 


这 个 配置 项 也 是 用 来 帮助 用 户 跟踪 调试 Nginx 的 。 它 接受 两 个 参数 : stop 和 abort。Nginx 
在 一 些 关 键 的 错误 逻辑 中 Nginx 1.0.14 版 本 中 有 8 处 ) 设置 了 调试 点 。 如 果 设 置 了 
debug points 为 stop， 那 么 Nginx 的 代码 执行 到 这 些 调试 点 时 就 会 发 出 SIGSTOP 信 和 号 以 用 于 调 
试 。 如 果 debug points 设 置 为 abort， 则 会 产生 一 个 coredump 文 件 ， 可 以 使 用 gdb 来 得 看 Nginx 当 
时 的 各 种 信息 。 


通 第 不 会 使 用 这 个 配置 项 。 
(5) 仪 对 指定 的 客户 端 输出 debug 级 别 的 日 志 


语法 : debug connection[IP|ICIDR] 
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这 个 配置 项 实际 上 属于 事件 类 配置 ， 因 此 ， 它 必须 放 在 events{...} 中 才 有 效 。 它 的 值 可 
以 是 人 PP 地 址 或 CIDR 地 址 ， 例 如 : 





events { 
debug connection 10.224.66.14; 
debug connection 10.224.57.0/24; 
} 


这 样 ， 仅 仅 来 自 以 上 了 下 地 址 的 请 求 才 会 输出 debug 级 别 的 日 志 ， 其 他 请 求 仍然 沿用 
error_log 中 配置 的 日 志 级 别 。 








上 面 这 个 配置 对 修复 Bug 很 有 用 ， 特 别 是 定位 高 并 发 请 求 下 才 会 发 生 的 问题 。 


@ 注意 ”使 用 debug_connection 前 ， 需 确保 在 执行 configure 时 已 经 加 入 了 --with-debug 参 


数 ， 否 则 不 会 生效 。 
(6) 限制 coredump 核 心 转 储 文件 的 大 小 
语法 : worker rlimit core size; 


在 Linux 系 统 中 ， 当 进程 发 生 错误 或 收 到 信和 号 而 终止 时 ， 系 统 会 将 进程 执行 时 的 内 存 内 
容 ( 核 心 映 像 ) 写 入 一 个 文件 (core 文 件 ) ， 以 作为 调试 之 用 ， 这 就 是 所 谓 的 核心 转 储 
(core dumps) 。 当 Nginx 进 程 出 现 一 些 非法 操作 (如 内 存 越界 ) 导致 进程 直接 被 操作 系统 强 
制 结束 时 ， 会 生成 核心 转 储 core 文 件 ， 可 以 从 core 文 件 获 取 当 时 的 堆栈 、 寄 存 器 等 信息 ， 从 
而 帮助 我 们 定位 问题 。 但 这 种 core 文 件 中 的 许多 信息 不 一 定 是 用 户 需 要 的 ， 如 果 不 加 以 限 
制 ， 那 么 可 能 一 个 core 文 件 会 达到 几 GB， 这 样 随便 coredumps 几 次 就 会 把 磁盘 占 满 ， 引 发 严 
重 问 题 。 通 过 worker Trlimit _ core 配置 可 以 限制 core 文 件 的 大 小 ， 从 而 有 效 帮 助 用 户 定位 问 


证 。 











(7) 指定 coredump 文 件 生成 目录 


语法 : working directory path; 
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worker 进 程 的 工作 目录 。 这 个 配置 项 的 唯一 用 途 就 是 设置 coredump 文 件 所 放置 的 目录 ， 
协助 定位 问题 。 因 此 ， 需 确保 worker 进 程 有 权限 向 working_directory 指 定 的 目录 中 写 入 文 
件 。 





2.3.2 ”正常 运行 的 配置 项 





下 面 是 正常 运行 的 配置 项 的 相关 介绍 。 
(1) 定义 环境 变量 
语法 : env VARIVAR=VALUE 


这 个 配置 项 可 以 让 用 户 直 接 设 置 操作 系统 上 的 环境 变量 。 例 如 : 





env TESTPATH=/tmp/; 





(2) 嵌入 其 他 配置 文件 
语法 : includepathfile; 


include 配 置 项 可 以 将 其 他 配置 文件 艇 入 到 当前 的 nginx.conf 文 件 中 ， 它 的 参数 既 可 以 是 绝 
对 路 径 ， 也 可 以 是 相对 路 径 〈 相 对 于 Nginx 的 配置 目录 ， 即 nginx.conf 折 在 的 目录 ) ， 例 如 


include mime.types; 
include vhost/*.conf; 


可 以 看 到 ， 参 数 的 值 可 以 是 一 个 明确 的 文件 名 ， 也 可 以 是 含有 通配符 * 的 文件 名 ， 同 时 
可 以 一 次 租 入 多 个 配置 文件 。 


(3) pid 文 件 的 路 径 


语法 : pid path/file; 
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默认 : pid logs/nginx.pid; 


保存 master 进 程 了 的 pid 文 件 存放 路 径 。 默 认 与 configure 执 行 时 的 参数 “--pid-path”" 所 指定 
的 路 径 是 相同 的 ， 也 可 以 随时 修改 ， 但 应 确保 Nginx 有 权 在 相应 的 目标 中 创建 pid 文 件 ， 该 文 
件 直接 影响 Neginx 是 否 可 以 运行 。 





(4) Nginx worker 进 程 运 行 的 用 户 及 用 户 组 
语法 : user username[groupname]; 
默认 : user nobody nobody: 


user 用 于 设置 master 进 程 启动 后 ，fork 出 的 worker 进 程 运 行 在 哪个 用 户 和 用 户 组 下 。 当 按 
照 “user username:” 设 置 时 ， 用 户 组 名 与 用 户 名 相同 。 


各 用户 在 configure 命 令 执行 时 使 用 了 参数 --user=username 和 --group=groupname， 此 时 
nginx.conf 将 使 用 参数 中 指定 的 用 户 和 用 户 组 。 


(5) 指定 Nginx worker 进 程 可 以 打开 的 最 大 句柄 描述 符 个 数 
语法 : worker rlimit nofile limit: 

设置 一 个 worker 进 程 可 以 打开 的 最 大 文件 句柄 数 。 

(6) 限制 信号 队列 

语法 : worker rlimit sigpending limit; 


设置 每 个 用 户 发 往 Nginx 的 信号 队列 的 大 小 。 也 就 是 说 ， 当 某 个 用 户 的 信号 队列 满 了 ， 
这 个 用 户 再 发 送 的 信号 量 会 被 丢掉 。 





HT 


的 配置 项 


2.3.3 ”优化 性 能 
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下 面 是 优化 性 能 的 配置 项 的 相关 介绍 。 
(1) Nginx worker 进 程 个 数 

语法 : worker processes number; 

默认 : worker processes 1; 


在 masterworker 运 行 方式 下 ， 定 义 worker 进 程 的 个 数 。 








worker 进 程 的 数量 会 直接 影响 性 能 。 那 么 ， 用 户 配 置 多 少 个 worker 进 程 才 好 呢 ? 这 实际 
上 与 业务 需求 有 关 。 


每 个 worker 进 程 都 是 单线 程 的 进程 ， 它 们 会 调用 各 个 模块 以 实现 多 种 多 样 的 功能 。 如 果 
这 些 模块 确认 不 会 出 现 阻 塞 式 的 调 有 用， 那么， 有 多 少 CPU 内 核 就 应 该 配置 多 少 个 进程 ; 反 
之 ， 如 果 有 可 能 出 现 阻塞 式 调用 ， 那 么 需要 配置 稍 多 一 些 的 worker 进 程 。 








例如 ， 如 果 业 务 方面 会 致使 用 户 请 求 大 量 读 取 本 地 磁盘 上 的 静态 资源 文件 ， 而 且 服 务 央 
上 的 内 存 较 小 ， 以 至 于 大 部 分 的 请 求 访问 静态 资源 文件 时 部 必须 读 取 磁 盘 〈 磁 类 的 寻 址 是 绥 
慢 的 ) ， 而 不 是 内 存 中 的 磁盘 缓存 ， 那 么 磁盘 IO 调用 可 能 会 阻塞 住 worker 进 程 少 量 时 间 ， 进 
而 导致 服务 整体 性 能 下 降 。 


多 worker 进 程 可 以 充分 利用 多 核 系 统 架 构 ， 但 知 worker 进 程 的 数量 多 于 CPU 内 核 数 ， 那 
么 会 增 大 进程 间 切 换 带 来 的 消耗 〈Linux 是 抢占 式 内 核 ) 。 一 般 情 况 下 ， 用 户 要 配置 与 CPU 内 
核 数 相 等 的 worker 进 程 ， 并 且 使 用 下 面 的 worker_ cpu affinity 配 置 来 绑 定 CPU 内 核 。 


(2) 绑 定 Nginx worker 进 程 到 指定 的 CPU 内 核 


语法 : worker cpu affinity cpumask[cpumask...] 





为 什么 要 绑 定 worker 进 程 到 指定 的 CPU 内 核 呢 ? 假定 每 一 个 worker 进 程 都 是 非常 繁忙 
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的 ， 如 果 多 个 worker 进 程 都 在 抢 同 一 个 CPPU， 那 么 这 就 会 出 现 同步 问题 。 反 之 ， 如 果 每 一 个 
worker 进 程 都 独 享 一 个 CPU， 束 在 内 核 的 调度 策略 上 实现 了 完全 的 并 发 。 


例如 ， 如 果 有 4 园 CPU 内 核 ， 就 可 以 进行 如 下 配置 : 





worker processes 4; 
worker cpu affinity 1000 0100 0010 0001; 





er 注意 wotket_cpu_affinity 配 置 仅 对 Linux 操 作 系 统 有 效 。Linux 操 作 系 统 使 用 


sched_setaffinity0 系统 调用 实现 这 个 功能 。 
(3) SSL 人 硬件 加 速 
语法 : ss]_engine device; 


如 果 服 务 器 上 有 SSL 人 硬件 加 速 设备 ， 那 么 就 可 以 进行 配置 以 加 快 SSL 协 议 的 处 理 速度 。 
用 户 可 以 使 用 OpenSSL 提 供 的 命令 来 查看 是 否 有 SSL 便 件 加 速 设备 : 

















openssl engine -t 





(4) 系统 调用 gettimeofday 的 执行 频率 
语法 : timer resolution ft: 


默认 情况 下 ， 每 次 内 核 的 事件 调用 (如 epoll、select、poll、kqueue 等 ) 返回 时 ， 都 会 执 
行 一 次 gettimeofday， 实 现 用 内 核 的 时 钟 来 更 新 Nginx 中 的 缓存 时 钟 。 在 早期 的 Linux 内 核 中 ， 
gettimeofday 的 执行 代价 不 小 ， 因 为 中 间 有 一 次 内 核 态 到 用 户 态 的 内 存 复 制 。 当 需要 降低 
gettimeofday 的 调用 频率 时 ， 可 以 使 用 timer resolution 配 置 。 例 如 ，“timer resolution 
100ms; ”表示 至 少 每 100ms 才 调用 一 次 gettimeofday。 


但 在 目前 的 大 多 数 内 核 中 ， 如 x86-64 体 系 架构 ，gettimeofday 只 是 一 次 vsyscall， 仅 仅 对 共 
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译 内 存 页 中 的 数据 做 访问 ， 并 不 是 通常 的 系统 调用 ， 代 价 并 不 大 ， 一 般 不 必 使 用 这 个 配置 。 
而 且 ， 如 宋 硕 望 日 志文 件 中 每 行 打印 的 时 间 更 准确 ， 也 可 以 使 用 它 。 


(5) Nginx worker 进 程 优 先 级 设置 
语法 : worker priority nice; 
默认 :worker priority 0; 
该 配置 项 用 于 设置 Nginx worker 进 程 的 nice 优先 级 。 


在 Linux 或 其 他 类 UNIX 操 作 系 统 中 ， 当 许多 进程 都 处 于 可 执行 状态 时 ， 将 按照 所 有 进程 
的 优先 级 来 决定 本 次 内 核 选 择 哪 一 个 进程 执行 。 进 程 所 分 配 的 CPU 时 间 片 大 小 也 与 进程 优先 
级 相关 ， 优 先 级 越 高 ， 进 程 分 配 到 的 时 间 瞩 也 就 越 大 《〈 例 如， 在 默认 配置 下 ， 节 小 的 时 间 广 
只 有 Sms， 节 大 的 时 间 片 则 有 800ms) 。 这 样 ， 优 先 级 高 的 进程 会 占有 更 多 的 系统 资源 。 





优先 级 由 静态 优 移 级 和 内 核 根 据 进 程 执行 情况 所 做 的 动态 调整 《目前 只 有 +5$ 的 调整 ) 共 
同 决定 。mice 值 是 进程 的 静态 优先 级 ， 它 的 取 值 范围 是 -20~+19，-20 是 最 高 优先 级 ，+19 是 
最 低 优先 级 。 因 此 ， 如 宁 用 户 和 希望 Nginx 占 有 更 多 的 系统 资源 ， 那 么 可 以 把 nice 值 配置 得 更 小 
一 些 ， 但 不 建议 比 内 核 进 程 的 nice 值 “通常 为 -5)〉 还 要 小 。 


2.3.4 事件 类 配置 项 





下 面 是 事件 类 配置 项 的 相关 介绍 。 
(1) 是否 打开 accept 锁 
语法 : accept mutex[onloff] 


默认 :accept mutext on; 
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accept_mutex 是 Nginx 的 负载 均衡 锁 ， 本 书 会 在 第 9 革 事 件 处 理 框架 中 详 述 Nginx 是 如 何 实 
现 负 载 均衡 的 。 这 里 ， 读 者 仅 需 要 知道 accept_mutex 这 把 锁 可 以 让 多 个 worker 进 程 轮流 地 、 
序列 化 地 与 新 的 客户 端 建 并 TCP 连 接 。 当 菜 一 个 worker 进 程 建立 的 连接 数量 达到 
worker_connections 配 置 的 最 大 连接 数 的 7/8 时 ， 会 大 大 地 减 小 该 worker 进 程 试 图 建 并 新 TCP 连 
接 的 机 会 ， 以 此 实现 所 有 worker 进 程 之 上 处 理 的 客户 剖 请 求 数 尽量 接近 。 





accept 锁 默认 是 打开 的 ， 如 果 关 闭 它 ， 那 么 建立 TCP 连 接 的 耗 时 会 更 短 ， 但 worker 进 程 
之 间 的 负载 会 非常 不 均衡 ， 因 此 不 建议 关闭 它 。 


(2) lock 文 件 的 路 径 
语法 : lock file path/file; 
默认 : lock file logs/nginx.lock:; 


accept 锁 可 能 需要 这 个 lock 文 件 ， 如 果 accept 锁 关闭 ，lock file 配 置 完全 不 生效 。 如 果 打 
开 了 accept 锁 ， 并 且 由 于 编译 程序 、 操 作 系统 架构 等 因素 导致 Neginx 不 支持 原子 锁 ， 这 时 才 会 
用 文件 锁 实现 accept 锁 (14.8.1 将 会 介绍 文件 锁 的 用 法 ) ， 这 样 lock file 指 定 的 lock 文 件 才 
会 生效 。 








er 注意 “在 基于 i386、AMD64、Spatc64、PPC64 体 系 架 构 的 操作 系统 上 ， 若 使 用 
GCC、Intel C++、SunPro C++ 编译 器 来 编译 Neinxg， 则 可 以 肯定 这 时 的 Nginx 是 支持 原子 锁 
的 ， 因 为 Nginx 会 利用 CPU 的 特性 并 用 汇编 语言 来 实现 它 (可 以 参考 14.3 节 x86 架 构 下 原子 操 


作 的 实现 ) 。 这 时 的 lock_file 配 置 是 没有 意义 的 。 
(3) 使 用 accept 锁 后 到 真正 建立 连接 之 间 的 延迟 时 间 
语法 : accept mutex delay Nms; 


默认 : accept mutex delay 500ms; 
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在 使 用 accept 锁 后 ， 同 一 时 间 只 有 一 个 worker 进 程 能 够 取 到 accept 饥 。 这 个 accept 锁 不 是 
阻塞 锁 ， 如 果 取 不 到 会 立刻 返回 。 如 果 有 一 个 worker 进 程 试 图 取 accept 锁 而 没有 取 到 ， 它 至 
少 要 等 accept mutex_ delay 定义 的 时 间 间 隔 后 才能 再 次 试 网 取 锁 。 


(4) 批量 建立 新 连接 
语法 : multi accept[onloff]; 
默认 : multi accept off 


当 事 件 模 型 通知 有 新 连接 时 ， 尺 可 能 地 对 本 次 调度 中 客户 端 友 起 的 所 有 TCP 请 求 痢 建 并 
连接 。 


(5) 选择 事件 模型 


语法 : use[kqueuelrtsiglepolll//dev/polllselectlpollleventport]; 





天 认 : Nginx 会 自动 使 用 最 适合 的 事件 模型 。 





对 于 Linux 操 作 系统 来 说 ， 可 供 选择 的 事件 驱动 模型 有 poll、select、epoll 三 种 。epoll 当 
然 是 性 能 最 高 的 一 种 ， 在 9.6 节 会 解释 epoll 为 什么 可 以 处 理 大 并 发 连接 。 


(6) 每 个 worker 的 最 大 连接 数 
语法 : worker _connections number; 


定义 每 个 worker 进 程 可 以 同时 处 理 的 最 大 连接 数 。 
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2.4 用 HTTP 核 心 模 块 配置 一 个 静态 Web 服 务 器 





静态 Web 服 务 器 的 主要 功能 由 ngx _http_ core _ module 模块 (HTTP 框 架 的 主要 成 员 ) 实现 ， 
当然 ， 一 个 完整 的 静态 Web 服 务 器 还 有 许多 功能 是 由 其 他 的 HTTP 模块 实现 的 。 本 节 主 要 讨 
论 如 何 配置 一 个 包含 基本 功能 的 静态 Web 服 务 器 ， 文 中 会 完整 地 说 明 ngx_http_core_module 模 
块 提供 的 配置 项 及 变量 的 用 法 ， 但 不 会 过 多 说 明 其 他 HTTP 模 块 的 配置 项 。 在 阅读 完 本 节 内 
容 后 ， 读 者 应 当 可 以 通过 简单 的 查询 相关 模块 (如 ngx_http_gzip_filter_module、 
ngx_http_image filter_ module 等 ) 的 配置 项 说 明 ， 方 便 地 在 nginx.conf 配 置 文件 中 加 入 新 的 配置 
项 ， 从 而 实现 更 多 的 Web 服 务 器 功能 。 








除了 2.3 节 提 到 的 基本 配置 项 外 ， 一 个 典型 的 静态 Web 服 务 器 还 会 包含 多 个 server 块 和 
location 块 ， 例 如 : 





http { 
gzip on; 
upstream { 


server { 
listen localhost:80; 


location /webstatic { 
if 


} 


root optwebresource; 


} 
location ~* .(jpgljpeglpng|ljpelgif)$ { 
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} 
} 


server { 


所 有 的 HTTP 配 置 项 都 必须 直属 于 http 块 、server 块 、location 块 、upstream 块 或 if 块 等 
(HTTP 配 置 项 自然 必须 全 部 在 http{} 块 之 内 ， 这 里 的 “直属 于 ”是 指 配 置 项 直接 所 属 的 大 括号 
对 应 的 配置 块 ) ， 同 时 ， 在 描述 每 个 配置 项 的 功能 时 ， 会 说 明 它 可 以 在 上 述 的 哪个 块 中 存 
在 ， 因 为 有 些 配置 项 可 以 任意 地 出 现在 某 一 个 块 中 ， 而 有 些 配置 项 只 能 出 现在 特定 的 块 中 ， 
在 第 4 章 介 绍 自 定义 配置 项 的 读 取 时 ， 相 信 读 者 就 会 体会 到 这 种 设计 思路 。 











Nginx 为 配置 一 个 完整 的 静态 Web 服 务 器 提供 了 非 营 多 的 功能 ， 下 面 会 把 这 些 配置 项 分 为 
以 下 8 类 进行 详 述 : 虚拟 主机 与 请 求 的 分 发 、 文 件 路 径 的 定义 、 内 存 及 磁盘 资源 的 分 配 、 网 
络 连接 的 设置 、MIME 类 型 的 设置 、 对 客户 端 请 求 的 限制 、 文 件 操作 的 优化 、 对 客户 端 请 求 
的 特殊 处 理 。 这 种 划分 只 是 为 了 帮助 大 家 从 功能 上 理解 这 些 配置 项 。 





在 这 之 后 会 列 出 ngx_http_core module 模 块 提 供 的 变量 ， 以 及 简单 说 明 它 们 的 意义 。 





2.4.1 虚拟 主机 与 请 求 的 分 发 





由 于 人 P 地 址 的 数量 有 限 ， 因 此 经 常 存在 多 个 主机 域名 对 应 着 同一 个 人 PP 地址 的 情况 ， 这 时 
在 nginx.conf 中 就 可 以 按照 server_name《〈 对 应 用 户 请 求 中 的 主机 域名 ) 并 通过 server 块 来 定义 
虚拟 主机 ， 每 个 server 块 就 是 一 个 虚拟 主机 ， 它 只 处 理 与 之 相对 应 的 主机 域名 请 求 。 这 样 ， 
一 台 服 务 器 上 的 Nginx 束 能 以 不 同 的 方式 处 理 访问 不 同 主机 域名 的 HTTP 请 求 了 。 





(1) 监听 端口 


语法 : listen address:port[default(deprecated in 0.8.21)ldefault server| 
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[backlos=numlrcvbuf-sizelsndbuf-sizelaccept filter=filterldeferredlbindlipv6only=[onloff||ss1]]; 默 
认 : listen 80: 


配置 块 : server 


listen 参 数 决 定 Nginx 服 务 如 何 监听 端口 。 在 listen 后 可 以 只 加 了 王 地 址 、 端 口 或 主机 名 ， 非 
各 灵活 ， 例 如 : 





listen 127.0.0.1:8000; 
L1Gen L2730,0.13 # 注 意 : 不 加 端口 时 ， 默 认 监 听 


80 端 口 


listen 8000; 
listen *:8000; 
listen localhost:8000; 





如 果 服 务 器 使 用 IPv6 地 址 ， 那 么 可 以 这 样 使 用 : 





listen [::]:8000; 
listen [fe80::1]; 
listen [:::a8c9:1234]:80; 





在 地 址 和 端口 后 ， 还 可 以 加 上 其 他 参数 ， 例 如 : 





listen 443 default server ssl; 
listen 127.0.0.1 default server accept filter=dataready backlog=1024; 





下 面 说 明 listen 可 用 参数 的 意义 。 


default: 将 所 在 的 server 块 作为 整个 Web 服 务 的 默认 server 块 。 如 果 没 有 设置 这 个 参数 ， 
那么 将 会 以 在 nginx.conf 中 找到 的 第 一 个 server 块 作为 默认 server 块 。 为 什么 需要 默认 虚拟 主机 
呢 ? 当 一 个 请 求 无 法 匹配 配置 文件 中 的 所 有 主机 域名 时 ， 就 会 选用 默认 的 虚拟 主机 (在 11.3 
节 介 绍 默 认 主 机 的 使 用 ) 。 
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. backlog=num: 表示 TCP 中 backlog 队 列 的 大 小 。 默 认为 -1， 表 示 不 予 设置 。 在 TCP 建 
立 三 次 握手 过 程 中 ， 进 程 还 没有 开始 处 理 监 听 句 柄 ， 这 时 backlog 队 列 将 会 放置 这 些 新 连接 。 
可 如 果 backlog 队 列 已 满 ， 还 有 新 的 客户 端 试图 通过 三 次 握手 建立 TCP 连 接 ， 这 时 客户 端 将 会 
建立 连接 失败 。 


* tcvbuf=size: 设置 监听 句柄 的 SO_RCVBUF 参 数 。 
sndbuf=size: 设置 监听 句柄 的 SO_SNDBUF 参 数 。 
* accept_filter: 设置 accept 过 滤器 ， 只 对 FreeBSD 操 作 系 统 有 用 。 


" deferred: 在 设置 该 参数 后 ， 若 用 户 发 起 建立 连接 请 求 ， 并 且 完 成 了 TCP 的 三 次 握手 ， 
内 核 也 不 会 为 了 这 次 的 连接 调度 worket 进 程 来 处 理 ， 只 有 了 用户 真 的 发 送 请 求 数据 时 (内核 已 
经 在 网 卡 中 收 到 请 求 数据 包 ) ， 内 核 才 会 唤醒 worker 进 程 处 理 这 个 连接 。 这 个 参数 适用 于 大 
并 发 的 情况 下 ， 它 减轻 了 worker 进 程 的 负担 。 当 请 求 数据 来 临时 ，worker 进 程 才 会 开始 处 理 
这 个 连接 。 只 有 确认 上 面 所 说 的 应 用 场景 符合 自己 的 业务 需求 时 ， 才 可 以 使 用 deferred 配 
置 。 


. bind: 绑 定 当前 端口 /地 址 对 ， 如 127.0.0.1:8000。 只 有 同时 对 一 个 端口 监听 多 个 地 址 时 


ssl: 在 当前 监听 的 端口 上 建立 的 连接 必须 基于 SSL 协 议 。 
(2) 主机 名 称 
语法 : server_name name[.…]; 
默认 : server name""; 


配置 块 : server 
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server_name 后 可 以 跟 多 个 主机 名 称 ， 如 server name www.testweb.com 、 


download.testweb.com '。 


在 开始 处 理 一 个 HTTP 请求 时 ，Nginx 会 取出 header 头 中 的 Host， 与 每 个 server 中 的 
Server_name 进 行 匹配 ， 以 此 决定 到 底 由 哪 一 个 server 块 来 处 理 这 个 请 求 。 有 可 能 一 个 Host 与 
多 个 server 块 中 的 server name 都 匹配 ， 这 时 惑 会 根据 匹配 优先 级 来 选择 实际 处 理 的 server 块 。 
server_name 与 Host 的 匹配 优先 级 如 下 : 


1) 首先 选择 所 有 字符 串 完全 匹配 的 server_ name， 如 www.testweb.com 。 
2) 其 次 选择 通配符 在 前 面 的 server name， 如 *#.testweb.com。 
3) 再 次 选择 通配符 在 后 面 的 server_name， 如 www.testweb.* 。 
4) 最 后 选择 使 用 正则 表达 式 才 匹配 的 server_name， 如 ~ 人 testweb\comy$ 。 


实际 上 ， 这 个 规则 正 是 7.7 节 中 介绍 的 带 通配符 散 列 表 的 实现 依据 ， 同 时 ， 在 10.4 节 也 介 
绍 了 虚拟 主机 配置 的 管理 。 如 果 Host 与 所 有 的 server_name 都 不 匹配 ， 这 时 将 会 按 下 列 顺序 选 
择 处 理 的 server 块 。 


1) 优先 选择 在 listen 配 置 项 后 加 入 [defaultldefault server] 的 server 块 。 
2) 找到 匹配 listen 端 口 的 第 一 个 server 块 。 


如 果 server_name 后 跟着 空 字符 串 (如 server name";) ， 那 么 表示 匹配 没有 Host 这 个 


HTTP 头 部 的 请 求 。 


注意 Nginx 正 是 使 用 setvet_hame 配 置 项 针对 特定 Host 域 名 的 请 求 提供 不 同 的 服务 ， 


以 此 实现 虚拟 主机 功能 


(3) server names hash bucket size 
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语法 : server names hash bucket size Size; 
默认 : server names hash bucket size 32|64|128; 
配置 块 : http、server、location 


为 了 提高 快速 寻找 到 相应 server name 的 能 力 ，Nginx 使 用 散 列 表 来 存储 server name。 
server names hash bucket size 设 置 了 每 个 散 列 桶 占用 的 内 存 大 小 。 


(4) server names hash max size 
语法 : server names hash max size size; 
默认 :server names hash max size 512; 
配置 块 : http、server、location 


server names hash max size 会 影响 散 列 表 的 冲突 紊 。server names hash max size 越 大 ， 
消耗 的 内 存 就 越 多 ， 但 散 列 key 的 冲突 率 则 会 降低 ， 检 索 速 度 也 更 快 。 
server_names_hash_max _size 越 小 ， 消 耗 的 内 存 就 越 小 ， 但 散 列 key 的 冲突 率 可 能 增高 。 





(5) 重 定 同 主机 名 称 的 处 理 





语法 : server name in redirect onloff; 
默认 :， server name in redirect on; 


配置 块 : http、server 或 者 location 





该 配置 需要 配合 server_name 使 用 。 在 使 用 on 打开 时 ， 表 示 在 重 定向 请 求 时 会 使 用 
server_name 里 配置 的 第 一 个 主机 名 代 葵 原先 请 求 中 的 Host 头 部 ， 而 使 用 off 关 闭 时 ， 表 示 在 重 
定向 请 求 时 使 用 请 求 本 身 的 Host 头 部 。 
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(6) location 
语法 : ”location[=~~*~|@]/urit{...} 


配置 块 : server 





location 会 尝试 根据 用 户 请 求 中 的 URI 来 匹配 上 面 的 /uri 表 达 式 ， 如 果 可 以 匹配 ， 束 选择 
location{} 块 中 的 配置 来 处 理 用 户 请 求 。 当 然 ， 匹 配方 式 是 多 样 的 ， 下 面 介绍 location 的 匹配 
规则 。 


1) = 表示 把 URI 作 为 字符 串 ， 以 便 与 参数 中 的 uri 做 完全 匹配 。 例 如 : 





location =/{ 


# 只 有 当 用 户 请 求 是 


/时 ， 才 会 使 用 该 


location 下 的 配置 








2) ~ 表示 [匹配 URI 时 是 字母 大 小 写 敏感 的 。 


3) ~* 表 示 区 配 URI 时 忽略 字母 大 小 写 问题 。 


4) 入 表 示 匹 配 URI 时 只 需要 其 前 半 部 分 与 uri 参 数 匹 配 即 可 。 例 如 : 





location ^~ images { 
# 以 


images 开 始 的 请 求 都 会 匹配 上 
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5) @ 表 示 仅 用 于 Nginx 服 务 内 部 请 求 之 间 的 重 定向 ， 带 有 @ 的 location 不 直接 处 理 用 户 请 


当然 ， 在 uri 参 数 里 是 可 以 用 正则 表达 式 的 ， 例 如 : 


location ~* \. (gifljpgljpeg)sS { 
# 匹配 以 


.JPG、 


.jpeg 结 尾 的 请 求 








注意 ，1location 是 有 顺序 的 ， 当 一 个 请 求 有 可 能 匹配 多 个 location 时 ， 实 际 上 这 个 请 求 会 
被 第 一 个 location 处 理 。 


在 以 上 各 种 匹配 方式 中 ， 都 只 能 表达 为 “如 果 匹 配 .… 则 .…”。 如 果 需 要 表达 “如 果 不 匹 配 .… 
则 .…”， 就 很 难 直接 做 到 。 有 一 种 解决 方法 是 在 最 后 一 个 location 中 使 用 /作为 参数 ， 它 会 匹配 
所 有 的 HTTP 请 求 ， 这 样 就 可 以 表示 如 果 不 能 匹配 前 面 的 所 有 location， 则 由 “/”* 这 个 location 处 
理 。 例 如 : 


location / 


# /可 以 匹配 所 有 请 求 


2.4.2 ”文件 路 径 的 定义 
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下 面 介绍 一 下 文件 路 径 的 定义 配置 项 。 
1) 以 root 方 式 设置 资源 路 径 

语法 : ”root path: 

默认 : root html: 

配置 块 : http、server、location、if 


例如 ， 定 义 资源 文件 相对 于 HTTP 请 求 的 根 目录 。 





location /download/ { 
root optwebhtml; 
} 





在 上 面 的 配置 中 ， 如 果 有 一 个 请 求 的 URI 是 /download/index/test.html， 那 么 Web 服 务 器 将 
会 返回 服务 器 上 optwebhtmldownload/index/test.html 文 件 的 内 容 。 


(2) 以 alias 方 式 设置 资源 路 径 
语法 : alias path; 
配置 块 : location 


alias 也 是 用 来 设置 文件 资源 路 径 的 ， 它 与 root 的 不 同 点 主要 在 于 如 何 解读 紧 跟 location 后 
面 的 uri 参 数 ， 这 将 会 致使 alias 与 root 以 不 同 的 方式 将 用 户 请 求 映 射 到 真正 的 磁盘 文件 上 。 例 
如 ， 如 果 有 一 个 请 求 的 URI 是 /confnginx.conf， 而 用 户 实 际 想 访问 的 文件 
在 usrlocal/nginx/conf/nginx.conf， 那 么 想 要 使 用 alias 来 进行 设置 的 话 ， 可 以 采用 如 下 方式 : 





location conf f{ 
alias usr/local/nginx/conf/; 


} 
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如 果 用 root 设 置 ， 那 么 语句 如 下 所 示 : 





Location conf f{ 
root usr/local/nginx/; 


} 








使 用 alias 时 ， 在 URI 向 实际 文件 路 径 的 映射 过 程 中 ， 已 经 把 location 后 配置 的 /conf 这 部 分 
字符 串 丢 弃 挥 ， 因 此 ，/conf/nginx.conf 请 求 将 根据 alias pa 了 映射 为 path/nginx.conf。root 则 不 
然 ， 它 会 根据 完整 的 URI 请 求 来 映射 ， 因 此 ，/conf/nginx.conf 请 求 会 根据 root path 映 射 为 
path/conf/nginx.conf。 这 也 是 root 可 以 放置 到 http、server、location 或 if 块 中 ， 而 alias 只 能 放置 
到 location 块 中 的 原因 。 


alias 后 面 还 可 以 添加 正则 表达 式 ， 例 如 : 





location ~ ^/test/(\wt)\. (\w+)$ { 
alias usrlocal/nginx/$2/$1.5$2; 
} 





这 样 ， 请 求 在 访问 /tesVynginx.conf 时 ，Nginx 会 返回 wsrlocalnginx/confnginx.conf 文 件 中 的 


内 容 。 
(3) 访问 首页 
语法 : index file...: 
RR 认 : index index.html: 
配置 块 : http、server、location 


有 时 ， 访 问 站 点 时 的 URI 是 /， 这 时 一 般 是 返回 网 站 的 首页 ， 而 这 与 root 和 alias 都 不 同 。 
这 里 用 ngx http index module 模 块 提供 的 index 配 置 实现 。index 后 可 以 跟 多 个 文件 参数 ，Nginx 
将 


将 会 按照 顺序 来 访问 这 些 文件 ， 例 如 : 
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root path; 
index index.html htmlindex.php /index.php; 
} 





接收 到 请 求 后 ，Nginx 首 先 会 尝试 访问 path/index.php 文 件 ， 如 果 可 以 访问 ， 就 直接 返回 文 
件 内 容 结束 请 求 ， 否 则 再 试图 返回 pathhtmlindex.php 文 件 的 内 容 ， 依 此 类 推 。 





(4) 根据 HITP 返 回 码 重 定向 页 面 
语法 : error page code[code.….][=Fanswer-codejluril@named location 
配置 块 : http、server、location、if 


当 对 于 某 个 请 求 返 回 错误 码 时 ， 如 果 匹 配 上 了 error_ page 中 设置 的 code， 则 重 定 向 到 新 
的 URI 中 。 例 如 : 





error page 404 404.htmil; 
error page 502 503 504 50x.html; 
error page 403 http://example.com/forbidden.ntml 
error page 404 = Qfetch; 








注意 ， 虽 然 重 定 向 了 URI， 但 返回 的 HTTP 错误 码 还 是 与 原来 的 相同 。 用 户 可 以 通 
过 “一 "来 更 改 返回 的 错误 码 ， 例 如 : 





error page 404 =200 empty.gif; 
error page 404 =403 forbidden.gif; 

















也 可 以 不 指定 确切 的 返回 错误 码 ， 而 是 由 重 定 疝 后 实际 处 理 的 真实 结果 来 决定 ， 这 时 ， 
只 要 把 =” 后 面 的 错误 码 去 掉 即 可 ， 例 如 : 





error page 404 = /empty.gif; 





如 果 不 想 修改 URI， 只 是 想 让 这 样 的 请 求 重 定 同 到 男 一 个 location 中 进行 处 理 ， 那 么 可 以 


设置 : 
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二 一 


location / ( 

error page 404 Q@fallback; 
) 
location Qfallback ( 

proxy pass http://backend 





这 样 ， 返 回 404 的 请 求 会 被 反 同 代理 到 http://backend 上 游 服 务 器 中 处 理 。 
(5) 是 否 允 许 递 归 使 用 error page 

语法 : recursive_error pages[onloff]; 

默认 : recursive error pages off. 

配置 块 : http、server、location 

确定 是 否 允 许 递归 地 定义 error_page。 
(6) try files 

语法 : try files pathl[path2]uri; 


配置 块 : serverf、location 





try_files 后 要 跟 奉 干 路 径 ， 如 pathl path2...， 而 且 最 后 必须 要 有 uri 参 数 ， 意 义 如 下 : 笠 试 
按照 顺序 访问 每 一 个 path， 如 末 可 以 有 效 地 读 取 ， 束 在 接 癌 用 户 返 回 这 个 path 对 应 的 文件 结 
束 请 求 ， 否 则 继续 向 下 访问 。 如 果 所 有 的 path 都 找 不 到 有 效 的 文件 ， 就 重 定向 到 最 后 的 参数 
ui 上 。 因 此 ， 最 后 这 个 参数 uri 必 须 存在 ， 而 且 它 应 该 是 可 以 有 效 重 定向 的 。 例 如 : 

















try files systemmaintenance.ntml] S$uri S$uri/index.html S$uri.ntml @otnher; 
location Qother { 
proxy pass http://backend 
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上 上面 这 段 代码 表示 如 果 前 面 的 路 径 ， 如 systemmaintenance.html 等 ， 都 找 不 到 ， 束 会 反问 
代理 到 http://backend 服务 上 。 还 可 以 用 指定 错误 码 的 方式 与 error page 配合 使 用 ， 例 如 : 





location ff 
try files SUri Suri /error.phpc=404 =404; 
} 


2.4.3 内存 及 磁盘 资源 的 分 配 


下 面 介 绍 处 理 请 求 时 内 存 、 人 磁盘 资 源 分 配 的 配置 项 。 
(1) HTTP 包 体 只 存储 到 磁盘 文件 中 

语法 : client body in file_only onlcleanloff; 

默认 :client body in file only off, 


配置 块 : http、server、location 





当 值 为 非 of 时 ， 用 户 请 求 中 的 HITP 包 体 一 律 存储 到 磁盘 文件 中 ， 即 使 只 有 0 字 节 也 会 存 
储 为 文件 。 当 请 求 结束 时 ， 如 果 配 置 为 op， 则 这 个 文件 不 会 被 删除 (该 配置 一 般 用 于 调试 、 
定位 问题 ， 但 如 果 配 置 为 clean， 则 会 删除 该 文件 。 


(2) HTTP 包 体 尽量 写 入 到 一 个 内 存 buffer 中 
语法 : client body in single buffer onloff 
默认 :client body in single buffer off: 


配置 块 : http、server、location 





用 户 请 求 中 的 HTTP 包 体 一 律 存储 到 内 存 buffsr 中 。 当 然 ， 如 果 HTTP 包 体 的 大 小 超过 了 
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(3) 存储 HTTP 头 部 的 内 存 buffer 大 小 
语法 : client header buffer size size; 
默认 : client header buffer size 1k: 
配置 块 : http、server 


上 面 配置 项 定义 了 正常 情况 下 Nginx 接 收 用 户 请 求 中 HTTP header 部 分 (包括 HTTP 行 和 
HTTP 头 部 ) 时 分 配 的 内 存 buffer 大 小 。 有 时 ， 请 求 中 的 HITP header 部 分 可 能 会 超过 这 个 大 


小 ， 这 时 large_client header buffers 定 义 的 buffer 将 会 生效 。 
(4) 存储 超大 HITP 头 部 的 内 存 buffer 大 小 
语法 : large_client header buffers number size; 
默认 : large client header buffers 48k: 


配置 块 : http、server 





large_client header buffers 定 义 了 Nginx 接 收 一 个 超大 HTTP 头 部 请 求 的 buffer 个 数 和 每 个 
buffer 的 大 小 。 如 果 HTTP 请 求 行 (如 GETindex HITP/1.1) 的 大 小 超过 上 面 的 单个 buffsr， 则 
返回 "Request URI too large"(414)。 请 求 中 一 般 会 有 许多 header， 每 一 个 header 的 大 小 也 不 能 超 
过 单个 buffsr 的 大 小 ， 和 否则 会 返回 "Bad request"(400)。 当 然 ， 请 求 行 和 请 求 头 部 的 总 和 也 不 可 
以 超过 buffer 个 数 *buffer 大 小 。 


(5) 存储 HTTP 包 体 的 内 存 buffer 大 小 
语法 : client body buffer size size; 
默认 :client body buffer size 8k/16k: 
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配置 块 : http、server、location 


上 面 配置 项 定义 了 Nginx 接 收 HTTP 包 体 的 内 存 绥 冲 区 大 小 。 也 就 是 说 ，HTTP 包 体会 完 
接收 到 指定 的 这 块 缓存 中 ， 之 后 才 决 定 是 否 写 入 磁盘 。 





注意 ”如果 用 户 请 求 中 含有 HTTP 头 部 Content-Length， 并 且 其 标识 的 长 度 小 于 定义 
的 buffer 大 小 ， 那 么 Nginx 会 自动 降低 本 次 请 求 所 使 用 的 内 存 buffer， 以 降低 内 存 消耗 。 


(6) HTTP 包 体 的 临时 存放 目录 
语法 : client body temp path dir-path[levell[level2[level3]]] 
默认 : client body temp path client body temp; 


配置 块 : http、server、location 





上 面 配 置 项 定义 HTTP 包 体 存 放 的 临时 目录 。 在 接收 HTTP 包 体 时 ， 如 果 包 体 的 大 小 大 于 
client_body_buffer_size， 则 会 以 一 个 递增 的 整数 命名 并 存放 到 client_body_temp_path 指 定 的 目 
录 中 。 后 面 跟着 的 levell、level2、level3， 是 为 了 防止 一 个 目录 下 的 文件 数量 太 多 ， 从 而 导 
致 性 能 下 降 ， 因 此 使 用 了 level 参 数 ， 这 样 可 以 按照 临时 文件 名 最 多 再 加 三 层 目 录 。 例 如 : 





client body temp path optnginx/client temp 1 2; 








如 果 新 上 传 的 HTTP 包 体 使 用 00000123456 作 为 临时 文件 名 ， 就 会 被 存放 在 这 个 目录 中 。 





optnginx/client temp/6/45/00000123456 





(7) connection pool size 
语法 : connection pool size size; 


默认 : connection pool size 256; 


中 门人 中 站 NNn http://ww linuxorobe. con 





配置 块 : http、server 


Nginx 对 于 每 个 建立 成 功 的 TCP 连 接 会 预先 分 配 一 个 内 存 池 ， 上 面 的 size 配 置 项 将 指定 这 
个 内 存 池 的 初始 大 小 〈 即 ngx_connection 结构 体 中 的 pool 内 存 池 初始 大 小 ，9.8.1 节 将 介绍 这 
个 内 存 池 是 何 时 分 配 的 ) ， 用 于 减少 内 核对 于 小 块 内 存 的 分 配 次 数 。 需 层 重 设置 ， 因 为 更 大 
的 size 会 使 服务 器 消耗 的 内 存 增 多 ， 而 更 小 的 size 则 会 引发 更 多 的 内 存 分 配 次 数 。 





(8) request pool size 
语法 : request pool size Size; 
默认 :request pool size 4k:; 
配置 块 : http、server 


Nginx 开 始 处 理 HTTP 请 求 时 ， 将 会 为 每 个 请 求 都 分 配 一 个 内 存 池 ，size 配 置 项 将 指定 这 
个 内 存 池 的 初始 大 小 〔 即 ngx_http_request t 结 构 体 中 的 pool 内 存 池 初 始 大 小 ，11.3 节 将 介绍 这 
个 内 存 池 是 何 时 分 配 的 ) ， 用 于 减少 内 核对 于 小 块 内 存 的 分 配 次 数 。TCP 连 接 关 闭 时 会 销毁 
connection pool size 指 定 的 连接 内 存 池 ，HTTP 请 求 结束 时 会 销毁 request pool size 指 定 的 
HTTP 请 求 内 存 池 ， 但 它们 的 创建 、 销 毁 时 间 并 不 一 致 ， 因 为 一 个 TCP 连 接 可 能 被 复 用 于 多 
个 HTTP 请 求 。8.7 节 会 详 述 内 存 池 原理 。 





2.4.4 网 络 连接 的 设置 


下 面 介绍 网 络 连接 的 设置 配置 项 。 
(1) 读 取 HITP 头 部 的 超时 时 间 


语法 : client header timeout time 〈 默 认 单 位 : 秒 ) ; 
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默认 :client header timeout 60; 


配置 块 : http、server、location 





客户 端 与 服务 器 建立 连接 后 将 开始 接收 HTTP 头 部 ， 在 这 个 过 程 中 ， 如 果 在 一 个 时 间 间 


隔 《 超 时 时 间 ) 内 没有 读 取 到 客户 端 发 来 的 字 节 ， 则 认为 超时 ， 并 回 客 户 端 返回 
408("Request timed out") 响 应。 


端 一 


将 会 


(2) 读 取 HTTP 包 体 的 超时 时 间 
语法 : client_body timeout time (默认 单位 : 秒 ) ; 
默认 :client body timeout 60; 
配置 块 : http、server、location 


此 配置 项 与 client_header_ timeout 相似 ， 只 是 这 个 超时 时 间 只 在 恋 取 HTTP 包 体 时 才 有 


(3) 发 送 啊 应 的 超时 时 间 
语法 : send timeout time; 
默认 :， send timeout 60; 
配置 块 : http、server、location 


这 个 超时 时 间 是 发 送 响应 的 超时 时 间 ， 即 Nginx 服 务 器 向 客户 端 发 送 了 数据 包 ， 但 客户 
直 没 有 去 接收 这 个 数据 包 。 如 果 茶 个 连接 超过 send_timeout 定 义 的 超时 时 间 ， 那 么 Nginx 
关闭 这 个 连接 。 


(4) reset timeout connection 
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语法 : reset timeout connection onloff 
默认 : reset timeout connection off 
配置 块 : http、server、location 


连接 超时 后 将 通过 向 客户 端 发 送 RST 包 来 直接 重 置 连接 。 这 个 选项 打开 后 ，Nsginx 会 在 某 

连接 超时 后 ， 不 是 使 用 正常 情形 下 的 四 次 握手 关闭 TCP 连 接 ， 而 是 直接 向 用 户 发 送 RST 重 
置 包 ， 不 再 等 待 用 户 的 应 答 ， 直 接 释 放 Nginx 服 务 器 上 关于 这 个 套 接 字 使 用 的 所 有 缓存 〈 如 
TCP 滑 动 窗 口 ) 。 相 比 正 常 的 关闭 方式 ， 它 使 得 服务 器 避免 产生 许多 处 于 FIN_WAIT 1、 
FIN WAIT 2、TIME WAIT 状态 的 TCP 连 接 。 








注意 ， 使 用 RST 重 置 包 关闭 连接 会 市 来 一 些 问 题 ， 默 认 情 况 下 不 会 开局 。 
($5) lingering _ close 

语法 : lingering close offlonlalways; 

默认 : lingering close on ; 


配置 块 : http、server、location 








该 配置 控制 Nginx 关 闭 用 户 连 接 的 方式 。always 表 示 关 闭 用 户 连 接 前 必须 无 条 件 地 处 理 连 
接 上 所 有 用 户 发 送 的 数据 。off 表 示 关 闭 连接 时 完全 不 管 连接 上 是 否 已 经 有 准备 就 绪 的 来 自用 
户 的 数据 。on 是 中 间 值 ， 一 般 情况 下 在 关闭 连接 前 都 会 处 理 连接 上 的 用 户 发 送 的 数据 ， 除 了 
有 些 情 况 下 在 业务 上 认定 这 之 后 的 数据 是 不 必要 的 。 





(6) lingering time 


语法 : lingering time time; 
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配置 块 : http、server、location 


lingering close 启 用 后 ， 这 个 配置 项 对 于 上 传 大 文件 很 8 用。 上 文 讲 过 ， 当 用 户 请 求 的 
Content-Length 大 于 max_client_body_size 配 置 时 ，Nginx 服 务 会 立刻 同 用 户 发 送 413 (Request 
entity too large》 响 应 。 但 是 ， 很 多 客户 端 可 能 不 管 413 返 回 值 ， 仍 然 持 续 不 断 地 上 传 HTTP 
body， 这 时 ， 经 过 了 lingering time 设 置 的 时 间 后 ，Nginx 将 不 管用 户 是 否 仍 在 上 传 ， 都 会 把 连 
接 关闭 掉 。 





(7) lingering timeout 
语法 : lingering timeout time; 
默认 : lingering timeout 5s; 
配置 块 : http、server、location 


lingering_close 牛 效 后 ， 在 关闭 连接 前 ， 会 检测 是 否 有 用 户 发 送 的 数据 到 达 服 务 器 ， 如 采 
超过 lingering timeout 时 间 后 还 没有 数据 可 读 ， 惑 直接 关闭 连接 ; 人 否则， 必须 在 读 取 完 连 接 组 
冲 区 上 的 数据 并 丢弃 挥 后 才 会 关闭 连接 。 





(8) 对 某 些 浏览 器 禁用 keepalive 功 能 
语法 : keepalive disable[msie6lsafarilnone].… 
默认 :， keepalive disablemsie6 safari 
配置 块 : http、server、location 


HTTP 请 求 中 的 keepalive 功 能 是 为 了 让 多 个 请 求 复 用 一 个 HTTP 长 连接 ， 这 个 功能 对 服务 
器 的 性 能 提高 是 很 有 帮助 的 。 但 有 些 浏览 堪 ， 如 下 6 和 Safari， 它 们 对 于 使 用 keepalive 功 能 的 
POST 请 求 处 理 有 功能 性 问题 。 因 此 ， 针 对 下 6 及 其 早期 版 本 、Safari 浏 览 器 默认 是 禁 
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keepalive 功 能 的 。 
(9) keepalive 超 时 时 间 
语法 : keepalive timeout time 《默认 单位 : 秒 ) ; 
默认 :， keepalive timeout 75; 
配置 块 : http、server、location 


一 个 keepalive 连 接 在 闲置 超过 一 定时 间 后 (默认 的 是 75 秒 〉， 服 务 器 和 浏览 器 都 会 去 关 
闭 这 个 连接 。 当 然 ，keepalive_timeout 配 置 项 是 用 来 约束 Nginx 服 务 器 的 ，Nginx 也 会 按照 规范 


把 这 个 时 间 传 给 浏览 器 ， 但 每 个 浏览 器 对 待 keepalive 的 策略 有 可 能 是 不 同 的 。 








(10) 一 个 keepalive 长 连接 上 人 允许 承载 的 请 求 最 大 数 

语法 : keepalive requests mi 

默认 : keepalive requests 100; 

配置 块 : http、server、location 

一 个 keepalive 连 接 上 默认 最 多 只 能 发 送 100 个 请 求 。 
(11) tcp nodelay 

语法 : tcp_nodelay onloff 

默认 : tcp_nodelay on; 

配置 块 : http、server、location 


确定 对 keepalive 连 接 是 否 使 用 TCP_ NODELAY 选 项 。 
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(12) tcp_nopush 
语法 : tcp_nopush onloff 
默认 : tcp_nopush off: 
配置 块 : http、server、location 


在 打开 sendfile 选 项 时 ， 确 定 是 否 开启 FreeBSD 系 统 上 的 TCP NOPUSH 或 Linux 系 统 上 的 
TCP_CORK 功 能 。 打 开 tcp_nopush 后 ， 将 会 在 发 送 啊 应 时 把 整个 啊 应 包头 放 到 一 个 TCP 包 中 


2.4.$_ MIME 类 型 的 设置 


下 面 是 MIME 类 型 的 设置 配置 项 。 
* MIME type 与 文件 扩展 的 映射 
语法 : typet{...}; 

配置 块 : http、server、location 


定义 MIME type 到 文件 扩展 名 的 映射 。 多 个 扩展 名 可 以 映射 到 同一 个 MIME type。 例 如 : 





types { 
text/html HtmlLs 
text/html conf; 
image/gif if; 
image/jpeg jpg; 





. 默认 MIME type 
语法 : default type MIME-type; 
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默认 : default type text/plain:; 


配置 块 : http、server、location 








当 找 不 到 相应 的 MIME type 与 文件 扩展 名 之 间 的 映射 时 ， 使 用 默认 的 MIME type 作 为 
HTTP header 中 的 Content-Type。 


* types_hash_bucket_size 
语法 : types_hash bucket size size; 
四 认 : types_hash bucket size 32|64|128; 


配置 块 : http、server、location 





为 了 快速 寻找 到 相应 MIME type，Nginx 使 用 散 列 表 来 存储 MIME type 与 文件 扩展 名 。 
types_hash_bucket_size 设 置 了 每 个 散 列 桶 占用 的 内 存 大 小 。 


* types_hash_max_size 

语法 : types_hash max size Size; 
默认 :，types_hash max size 1024; 
配置 块 : http、server、location 


types_hash _ max _ size 影响 散 列 表 的 冲突 率 。types_hash _ max _size 越 大 ， 就 会 消耗 更 多 的 内 
存 ， 但 散 列 key 的 冲突 率 会 降低 ， 检 索 速 度 就 更 快 。types_hash max size 越 小 ， 消 耗 的 内 存 整 
越 小 ， 但 散 列 key 的 冲突 率 可 能 上 升 。 


2.4.6 ”对 客户 端 请 求 的 限制 
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下 面 介 绍 对 客户 端 请 求 的 限制 的 配置 项 。 
(1) 按 HTTP 方 法 名 限制 用 户 请 求 
语法 : 1limit except method...{...} 


配置 块 : location 











Nginx 通 过 limit_except 后 面 指定 的 方法 名 来 限制 用 户 请 求 。 方 法 名 可 取 值 包括 : GET、 
HEAD、 POST、 PUT、 DELETE、 MKCOL、 COPY、 MOVE、 OPTIONS、 PROPFIND. 
PROPPATCH、LOCK、UNLOCK 或 者 PATCH。 例 如 ; 








limit except GET { 
allow 192.168.1.0/32; 
deny all; 

} 








注意 ， 人 允许 GET 方 法 就 意味 着 也 人 允许 HEAD 方 法 。 因 此 ， 上 面 这 段 代 码 表示 的 是 禁 
GET 方 法 和 HEAD 方 法 ， 但 其 他 HTTP 方 法 是 允许 的 。 


(2) HTTP 请 求 包 体 的 最 大 值 
语法 : client max body size size; 
默认 :client max body Size 1m: 


配置 块 : http、server、location 





浏览 器 在 发 送 含 有 较 大 HTTP 包 体 的 请 求 时 ， 其 头 部 会 有 一 个 Content-Length 字 段 ， 
client max_body_size 是 用 来 限制 Content-Length 所 示 值 的 大 小 的 。 因 此 ， 这 个 限制 包 体 的 配置 
非常 有 用 处 ， 因 为 不 用 等 Nginx 接 收 完 所 有 的 HTTP 包 体 一 一 这 有 可 能 消耗 很 长 时 间 一 一 就 可 
以 告诉 用 户 请 求 过 大 不 被 接受 。 例 如 ， 用 户 试图 上 传 一 个 10GB 的 文件 ，Nginx 在 收 完 包头 
后 ， 发 现 Content-Length 超 过 client max body size 定 义 的 值 ， 就 直接 发 送 413("Request Entity 
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Too Large) 啊 应 给 客户 端 。 
(3) 对 请 求 的 限 速 
语法 : limit rate Speed; 
默认 : limit rate 0; 
配置 块 : http、server、location、if 


此 配置 是 对 客户 端 请 求 限 制 每 秒 传输 的 字 节 数 。speed 可 以 使 用 2.2.4 贡 中 提 到 的 多 种 单 
位 ， 默 认 参 数 为 0， 表 示 不 限 速 。 





针对 不 同 的 客户 端 ， 可 以 用 $limit_rate 参 数 执行 不 同 的 限 速 策略 。 例 如 : 





server { 
if ($slow) { 
set $limit rate 4k; 
} 
} 





(4) limit rate after 
语法 : limit rate after time; 
默认 : limit rate after 1m; 
配置 块 : http、server、location、if 


此 配置 表示 Nginx 回 客户 端 发 送 的 啊 应 长 度 超过 limit rate_after 后 才 开 始 限 速 。 例 如 : 





limit rate after lm; 
limit rate 100k; 





11.9.2 节 将 从 源码 上 介绍 limit rate after 与 limit rate 的 区 别 ， 以 及 HTTP 框 架 是 如 何 使 用 它 
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2.4.7 文件 操作 的 优化 


下 面 介绍 文件 操作 的 优化 配置 项 。 
(1) sendfile 系 统 调 用 

语法 : sendfile onloff 

默认 : sendfile o 储 


配置 块 : http、server、location 





可 以 司 用 Linux 上 的 sendfile 系 统 调用 来 发 送 文件 ， 它 减少 了 内 核 态 与 用 户 态 之 间 的 两 次 
内 存 复 制 ， 这 样 就 会 从 磁盘 中 读 取 文件 后 直接 在 内 核 态 发 送 到 网 卡 设备 ， 提 高 了 发 送 文件 的 
效率 。 


2) AIO 系 统 调用 

语法 : aio onloff 

默认 : aio off 

配置 块 : http、server、location 


此 配置 项 表示 是 人 否 在 FreeBSD 或 Linux 系 统 上 局 用 内 核 级 别 的 异步 文件 IO 功能 。 注 意 ， 
它 与 Sendfile 功 能 是 互 斥 的 。 


(3) directio 
语法 : directio size|off; 


默认 : directio off 
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配置 块 : http、server、location 


此 配置 项 在 FreeBSD 和 Linux 系 统 上 使 用 O_DIRECT 选 项 去 读 取 文 件 ， 缓 冲 区 大 小 为 size， 
通 稼 对 大 文件 的 读 取 速 度 有 优化 作用 。 注 意 ， 它 与 sendfile 功 能 是 互 斥 的 。 


(4) directio alignment 
语法 : directio alignment size; 
默认 : directio alignment 512:; 


配置 块 : http、server、location 





它 与 directio 配 合 使 用 ， 指 定 以 directio 方 式 读 取 文件 时 的 对 齐 方式 。 一 般 情 况 下 ，512B 
已 经 足够 了 ， 但 针对 一 些 高 性 能 文件 系统 ， 如 Linux 下 的 XFS 文 件 系统 ， 可 能 需要 设置 到 4KB 
作为 对 齐 方式 。 





(5) 打开 文件 缓存 
语法 : open file_cache max=N[inactive=time]lo 任 
默认 : open file cache off: 


配置 块 : http、server、location 





文件 缓存 会 在 内 存 中 存储 以 下 3 种 信息 : 

` 文件 句柄、 文件 大 小 和 上 次 修改 时 间 。 
已 经 打开 过 的 目录 结构 。 

` 没有 找到 的 或 者 没有 权限 操作 的 文件 信息 。 
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这 样 ， 通 过 该 取 组 存 就 减少 了 对 磁盘 的 操作 。 
该 配置 项 后 面 跟 3 种 参数 。 


` max: 表示 在 内 存 中 存储 元 素 的 最 大 个 数 。 当 达到 最 大 限制 数量 后 ， 将 采用 


LRU (Least Recently Used) 算法 从 缓存 中 淘汰 最 近 最 少 使 用 的 元 素 。 


.inactive: 表示 在 inactive 指 定 的 时 间 段 内 没有 被 访问 过 的 元 素 将 会 被 淘汰 。 默 认 时 间 为 


60 秒 。 
off: 关闭 缓存 功能 。 


例如 : 





open file cache max=1000 inactive=20s; 








(6) 是 否 缓存 打开 文件 错误 的 信息 
语法 : open file cache errors onloff: 
默认 : open file cache errors o 任 


配置 块 : http、server、location 





此 配置 项 表示 是 否 在 文件 缓存 中 缓存 打开 文件 时 出 现 的 找 不 到 路 径 、 没 有 权限 等 错误 信 


亚 


(7) 不 被 淘汰 的 最 小 访问 次 数 
语法 : open file cache min uses number; 


默认 : open file cache min uses 1; 
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配置 块 : http、server、location 


它 与 open file_ cache 中 的 inactive 参 数 配 合 使 用 。 如 果 在 inactive 指 定 的 时 间 段 内 ， 访 问 次 
数 超过 了 open file cache min uses 指 定 的 最 小 次 数 ， 那 么 将 不 会 被 淘汰 出 缓存。 


(8) 检验 缓存 中 元 素 有 效 性 的 频率 
语法 : open file cache valid time; 
默认 : open file cache valid 60s; 


配置 块 : http、server、location 





默认 为 每 60 秒 检查 一 次 缓存 中 的 元 素 是 否 仍 有 效 。 
2.4.8 对 客户 问 请 求 的 特殊 处 理 


下 面 介 绍 对 客户 端 请 求 的 特殊 处 理 的 配置 项 。 
(1) 忽略 不 合法 的 HTTP 头 部 

语法 : ignore invalid _ headers onloff: 

默认 : ignore invalid headers on: 

配置 块 : http、server 


如 果 将 其 设置 为 of， 那 么 当 出 现 不 合法 的 HITP 头 部 时 ，Nsginx 会 拒绝 服务 ， 并 直接 向 用 
户 发 送 400 (Bad Request) 错误 。 如 果 将 其 设置 为 on， 则 会 忽略 此 HTTP 头 部 。 


(2) HTTP 头 部 是 否 允 许 下 划 线 
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语法 : underscores in headers onloff 

默认 : underscores in headers off 

配置 块 : http、server 

默认 为 off， 表 示 HTTP 头 部 的 名 称 中 不 允许 带 * ”( 下 划 线 ) 。 
(3) 对 下 Modified-Since 头 部 的 处 理 策略 

语法 : 让 modified since[offlexactlbefore]; 

默认 : if modified since exact; 

配置 块 : http、server、location 


出 于 性 能 考虑 ，Web 浏 览 器 一 般 会 在 客户 端 本 地 缓存 一 些 文件 ， 并 存储 当时 获取 的 时 
这 样 ， 下 次 同 Web 服 务 嚣 获取 绥 存 过 的 资源 时 ， 束 可 以 用 下 Modified-Since 头 部 把 上 次 获 
取 的 时 间 撒 带 上 ， 而 下 modified_since 将 根据 后 面 的 参数 决定 如 何 处 理 企 Modified-Since 头 


部 。 
相关 参数 说 明 如 下 。 


.oO 任 : 表示 忽略 用 户 请 求 中 的 于 Modified-Since 头 部 。 这 时 ， 如 果 获 取 一 个 文件 ， 那 么 会 


常 地 返回 文件 内 容 。HTTP 响 应 码 通 常 是 200。 


. exact: 将 企 Modified-Since 头 部 包含 的 时 间 与 将 要 返回 的 文件 上 次 修改 的 时 间 做 精确 比 
较 ， 如 果 没 有 匹配 上 ， 则 返回 200 和 文件 的 实际 内 容 ， 如 果 匹 配 上 ， 则 表示 浏览 器 缓存 的 文 
件 内 容 已 经 是 最 新 的 了 ， 没 有 必要 再 返回 文件 从 而 浪费 时 间 与 带宽 了 ， 这 时 会 返回 304 Not 
Modified， 浏 览 器 收 到 后 会 直接 读 取 自己 的 本 地 缓存 。 


ee or on 





的 IfModified-Since 头 部 的 时 间 ， 就 会 向 客户 端 返 回 304 Not Modified。 
(4) 文件 未 找到 时 是 否 记录 到 error 日 志 
语法 : log not found onlo 任 
默认 : log not found on; 
配置 块 : http、server、location 


此 配置 项 表示 当 处 理 用 户 请 求 且 需 要 访问 文件 时 ， 如 果 没 有 找到 文件 ， 是 否 将 错误 日 志 
记录 到 errorlog 文 件 中 。 这 仅 用 于 定位 问题 。 


($5) merge slashes 
语法 : merge slashes onloff: 
默认 :， merge slashes on 
配置 块 : http、server、location 


此 配置 项 表示 是 否 合 并 相 邻 的 "”， 例 如 ，/estWa.txt， 在 配置 为 on 时 ， 会 将 其 匹配 为 
location/test/a.txt; 如 果 配 置 为 off， 则 不 会 匹配 ，URI 将 仍然 是 /test/a.txt。 


(6) DNS 解析 地 址 
语法 : resolver address...: 
配置 块 : http、server、location 


设置 DNS 名 字 解 析 服 务 器 的 地 址 ， 例 如 : 





ESOLVEeE 127.0,.0.1 1920,2:13 
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(7) DNS 解析 的 超时 时 间 
语法 : resolver timeout time; 
默认 : resolver timeout 30s; 
配置 块 : http、server、location 


此 配置 项 表示 DNS 解析 的 超时 时 间 。 





(8) 返回 错误 页 面 时 是 否 在 Server 中 注 明 Nginx 版 本 
语法 : ”server_tokens onlo 任 
默认 : server tokens on; 
配置 块 : http、server、location 


表示 人 处理 请 求 出 错时 是 否 在 啊 应 的 Server 头 部 中 标明 Nginx 版 本 ， 这 是 为 了 方便 定位 问 


2.4.9 ngx http core module 模 块 提 供 的 变量 


在 记录 access log 访问 日 志文 件 时 ， 可 以 使 用 ngx http_core module 模 块 处 理 请 求 时 所 产 
生 的 丰富 的 变量 ， 当 然 ， 这 些 变量 还 可 以 用 于 其 他 HTTP 模块 。 例 如 ， 当 URI 中 的 茶 个 参数 满 
足 设 定 的 条 件 时 ， 有 些 HTTP 模 块 的 配置 项 可 以 使 用 类 似 $arg _ PARAMETER 这样 的 变量 。 又 
如 ， 若 想 把 每 个 请 求 中 的 限 速 信息 记录 到 access 日 志文 件 中 ， 则 可 以 使 用 $limit rate 变 量 。 





表 2-1 列 出 了 ngx_http_core_module 模 块 提 供 的 这 些 变 量 。 


表 2-1 ngx_http_core_module 模 块 提 供 的 变量 
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2.$ 用 HTTP proxy module 配 置 一 个 反问 代理 服务 器 


反 向 代理 〈reverse proxy) 方式 是 指 用 代理 服务 器 来 接受 Internet 上 的 连接 请 求 ， 然 后 将 
请 求 转发 给 内 部 网 络 中 的 上 游 服务 器 ， 并 将 从 上 游 服务 器 上 得 到 的 结果 返回 给 Internet 上 请 求 
连接 的 客户 端 ， 此 时 代理 服务 器 对 外 的 表现 就 是 一 个 Web 服 务 器 。 充 当 反 向 代理 服务 器 也 是 
Nginx 的 一 种 常见 用 法 《〈《 反 向 代理 服务 器 必须 能 够 处 理 大 量 并 发 请 求 ) ， 本 节 将 介绍 Nginx 作 
为 HTTP 反 向 代理 服务 器 的 基本 用 法 。 














由 于 Nginx 具 有 “强悍 ”的 高 并 发 高 负载 能 力 ， 因 此 一 般 会 作为 前 端的 服务 器 直接 加 客户 
端 提供 静态 文件 服务 。 但 也 有 一 些 复杂 、 多 变 的 业务 不 适合 放 到 Nginx 服 务 嚣 上， 这 时 会 用 
Apache、Tomcat 等 服务 器 来 处 理 。 于 是 ，Nginx 通 常会 被 配置 为 既是 静态 Web 服 务 右 也 是 反问 
代理 服务 费 〈 如 图 2-3 所 示 ) ， 不 适合 Nginx 处 理 的 请 求 就 会 直接 转 及 到 上 游 服务 器 中 处 理 。 














Nginx Tomcat / Apache 等 
鹏 态 Weh 服 务 器 处 理 复杂 业务 的 动 
反 回 代理 服务 天 态 Web 上 服务 条 


图 2-3 ”作为 静态 Web 服 务 器 与 反 向 代理 服务 器 的 Nginx 
与 Squid 等 其 他 反 向 代理 服务 器 相 比 ，Nginx 的 反 向 代理 功能 有 自己 的 特点 ， 如 图 2-4 所 
































当 客 户 端 发 来 HTTP 请 求 时 ，Nginx 并 不 会 立刻 转发 到 上 游 服 务 器 ， 而 是 先 把 用 户 的 请 求 
《包括 HITP 包 体 ) 完整 地 接收 到 Nginx 所 在 服务 器 的 硬盘 或 者 内 存 中 ， 然 后 再 网 上游 服务 需 
发 起 连接 ， 把 缓存 的 客户 端 请 求 转 发 到 上 游 服务 器 。 而 Squid 等 代理 服务 器 则 采用 一 边 接收 
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客户 端 请 求 ， 一 边 转发 到 上 游 服 务 器 的 方式 。 





Nginx 的 这 种 工作 方式 有 什么 优 缺 点 昵 ? 很 明显 ， 缺 点 是 延长 了 一 个 请 求 的 处 理 时 间 ， 
并 增加 了 用 于 缓存 请 求 内 容 的 内 存 和 破 盘 空间 。 而 优点 则 是 降低 了 上 游 服 务 器 的 负载 ， 尽 量 
把 压力 放 在 Nginx 服 务 器 上 。 
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如 果 上 游 服 务 器 返回 内 
容 ， 则 不 会 先 完 整地 缓存 到 
Nginx 代 理 服 务 器 再 向 客户 
端 转发 ， 而 是 边 接 收 边 转发 


| 到 客户 端 


用 户 发 来 的 请 求 将 会 完 
整地 缓存 到 Nginx 代 理 服务 
船 ， 之 后 才 会 回 后 端 服务 
器 转发 ， 这 与 Squid 等 反问 
代理 服务 器 不 同 












































缓存 请 求 的 HTTP 包 体 


Nginx 反问 
代理 服务 器 





Nginx 反 加 代理 服 务 
器 可 以 根据 多 种 方案 
从 上 游 服 务 器 的 集群 
中 选择 一 台 。 它 的 负 
载 均 衡 方案 包括 按 IP 
地 址 做 散 列 等 








SS 
[®] 
NS f 
于 游 服务 需 上 游 服 务 履 上 游 服务 器 


A 


图 2-4 Nginx 作 为 反 向 代理 服务 器 时 转发 请 求 的 流程 


Nginx 的 这 种 工作 方式 为 什么 会 降低 上 游 服务 器 的 负载 呢 ? 通常 ， 客 户 端 与 代理 服务 器 
之 间 的 网 络 环境 会 比较 复杂 ， 多 半 是 “ 走 ” 公 网 ， 网 速 平 均 下 来 可 能 较 慢 ， 因 此 ， 一 个 请 求 可 
能 要 持续 很 久 才 能 完成 。 而 代理 服务 器 与 上 游 服务 器 之 间 一 般 是 “ 走 ” 内 网 ， 或 者 有 专线 连 
接 ， 传 输 速度 较 快 。Squid 等 反 向 代理 服务 器 在 与 客户 端 建立 连接 且 还 没有 开始 接收 HTTP 包 
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体 时 ， 就 已 经 向 上 游 服 务 器 建立 了 连接 。 例 如 ， 某 个 请 求 要 上 传 一 个 1GB 的 文件 ， 那 么 每 次 

Squid 在 收 到 一 个 TCP 分 包 〈 如 2KB) 时 ， 就 会 即时 地 向 上 游 服务 器 转发 。 在 接收 客户 端 完 整 
HTTP 包 体 的 漫长 过 程 中 ， 上 游 服务 器 始终 要 维持 这 个 连接 ， 这 直接 对 上 游 服 务 器 的 并 发 处 
理 能 力 提 出 了 挑战 。 


它 在 接收 到 完整 的 客户 端 请 求 ( 如 1GB 的 文件 ) 后 ， 才 会 与 上 游 服 务 器 

连接 转发 请 求 ， 由 于 是 内 网 ， 所 以 这 个 转发 过 程 会 执行 得 很 快 。 这 样 ， 一 个 客 己 端 请 求 

占用 上 游 服务 絮 的 连接 时 间 就 会 非常 短 ， 也 就 是 说 ，Nginx 的 这 种 反 回 代 理 方 案 主要 是 为 了 
降低 上 游 服务 器 的 并 发 压力 。 





Nginx 将 上 游 服 务 器 的 响应 转发 到 客户 端 有 许多 种 方法 ， 第 12 章 将 介绍 其 中 常见 的 两 种 
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2.5.1 负载 均衡 的 基本 配置 


作为 代理 服务 器 ， 一 般 都 需要 向 上 游 服 务 占 的 集群 转 及 请 求 。 这 里 的 负载 均衡 是 指 选择 
一 种 策略 ， 尽 量 把 请 求 平 均 地 分 布 到 每 一 台 上 游 服务 器 上 。 下 面 介 绍 负载 均衡 的 配置 项 。 





(1) upstream 块 
语法 : upstream name{...} 
配置 块 : http 


upstream 块 定义 了 一 个 上 洲 服 务 器 的 集群 ， 便 于 反问 代理 中 的 proxy_pass 使 用 。 例 如 : 


upstream backend { 
server backendl .example.com; 
server backend2 .example.com; 
server backend3.example.com; 











} 
server { 
location / { 
proxy pass http://backend; 
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(2 ) server 
语法 : server name[parameters]; 
配置 块 : upstream 


server 配 置 项 指定 了 一 台 上 游 服 务 器 的 名 字 ， 这 个 名 字 可 以 是 域名 、P 地 址 端口 、UNIX 
句柄 等 ， 在 其 后 还 可 以 跟 下 列 参数 。 


` weight=number: 设置 向 这 台 上 游 服务 器 转发 的 权重 ， 默 认为 1。 


. max_fails=numbet: 该 选项 与 fail_timeout 配 合 使 用 ， 指 在 fail_timeout 时 间 段 内 ， 如 果 向 
当前 的 上 游 服务 器 转发 失败 次 数 超过 number， 则 认为 在 当前 的 fail_timeout 时 间 段 内 这 台 上 游 
服务 器 不 可 用 。max_fails 默 认为 1， 如 果 设 置 为 0， 则 表示 不 检查 失败 次 数 。 

fail_timeout=time: fail_timeout 表 示 该 时 间 段 内 转发 失败 多 少 次 后 就 认为 上 游 服务 器 暂 
时 不 可 用 ， 用 于 优化 反 向 代理 功能 。 它 与 向 上 游 服务 器 建立 连接 的 超时 时 间 、 读 取 上 游 服务 
器 的 响应 超时 时 间 等 完全 无 关 。fail_timeout 默 认为 10 秒 。 


. down: 表示 所 在 的 上 游 服务 器 永久 下 线 ， 只 在 使 用 ip_hash 配 置 项 时 才 有 用 。 


. backup: 在 使 用 ip_hash 配 置 项 时 它 是 无 效 的 。 它 表示 所 在 的 上 游 服务 器 只 是 备份 服务 
器 ， 只 有 在 所 有 的 非 备 份 上 游 服务 器 都 失效 后 ， 才 会 向 所 在 的 上 游 服务 器 转发 请 求 。 


例如 : 





upstream backend { 
server backendl1 .example.com weight=5; 
server 127.0.0.1;8080 max fails=3 fail timeout=30s; 
server unix:/tmp/backend3; 


} 
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(3) ip_hash 
语法 : ip_hash; 
配置 块 : upstream 


在 有 些 场景 下 ， 我 们 可 能 会 希望 来 自 某 一 个 用 户 的 请 求 始终 落 到 固定 的 一 人 台 上 游 服务 器 
中 。 例 如 ， 假 设 上 游 服务 器 会 缓存 一 些 信息 ， 如 条 同一 个 用 户 的 请 求 任意 地 转发 到 集群 中 的 
任 一 台 上 游 服 务 嚣 中， 那么 每 一 台 上 游 服 务 器 都 有 可 能 会 缓存 同一 份 信 息 ， 这 既 会 造成 资源 
的 浪费 ， 也 会 难以 有 效 地 管理 缓存 信息 。ip_hash 就 是 用 以 解决 上 述 问题 的 ， 它 首先 根据 客户 
端的 下地 址 计算 出 一 个 key， 将 key 按 照 upstream 集 群 里 的 上 游 服 务 器 数量 进行 取 模 ， 然 后 以 取 
模 后 的 结果 把 请 求 转发 到 相应 的 上 游 服 务 器 中 。 这 样 就 确保 了 同一 个 客户 端的 请 求 只 会 转发 
到 指定 的 上 游 服务 器 中 。 














ip_hash 与 weight《〈 权 重 ) 配置 不 可 同时 使 用 。 如 果 upstream 集 群 中 有 一 人 台 上 游 服务 器 暂 
时 不 可 用 ， 不 能 直接 删除 该 配置 ， 而 是 要 down 参 数 标识 ， 确 保 转发 策略 的 一 贯 性 。 例 如 : 








upstream backend { 
ip hash; 
server backendl1 .example.com; 
server backend2 .example .com; 
server backend3.example.com down; 
server backend4 .example.com; 








(4) 记录 日 志 时 支持 的 变量 


如 果 需 要 将 负载 均衡 时 的 一 些 信息 记录 到 access log 日 志 中 ， 那 么 在 定义 日 志 格 式 时 可 
以 使 用 负载 均衡 功能 提供 的 变量 ， 见 表 2-2。 


表 2-2 访问 上 游 服务 器 时 可 以 使 用 的 变量 
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变量 名 意 义 


S$upstream addr 处 理 请 求 的 上 游 服 务 需 地 址 

$upstream cache status 表示 是 否 命中 缓存 ， 取 值 范围 . MISS、EXPIRED、UPDATING、STALE、HIT 
$upstream status 上 游 服务 需 返 回 的 响应 中 的 HTTP 响应 人 码 

$upstream response time 上 游 服务 器 的 响应 时 间 ， 精 度 到 毫秒 

$upstream http SHEADER HTTP 的 头 部 ， 如 upstream http_ host 


例如 ， 可 以 在 定义 access_log 访 问 日 志 格 式 时 使 用 表 2-2 中 的 变量 。 





log format timing "Sremote addr - Sremote user [$time local] $request ' 
'upstream response time S$upstream response time ' 
'msec $msec request time $request time'; 

log format up head '$remote addr - S$remote user [$time local] $request ' 
'upstream http content type S$upstream nttp content type'; 














2.5.2 ”反问 代理 的 基本 配置 


下 面 介 绍 反 回 代理 的 基本 配置 项 。 
(1) proxy pass 
语法 : proxy pass URL; 


配置 块 : location、if 








此 配置 项 将 当前 请 求 反 同 代理 到 URL 参 数 指定 的 服务 器 上 ，URL 可 以 是 主机 名 或 PP 地 址 
加 端口 的 形式 ， 例 如 : 





proxy pass http://localhost:8000/uri/ 





也 可 以 是 UNIX 人 句柄 : 





proxy pass http://unix:/path/to/backend.socket:/uri/ 
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还 可 以 如 上 节 负 载 均 衡 中 所 示 ， 和 直接 使 用 upstream 块 ， 例 如 : 





upstream backend { 


} 
server { 
location / { 
proxy pass http://backend 





用 户 可 以 把 HTTP 转 换 成 更 安全 的 HTTPS， 例 如 : 





proxy pass httpssi/192 168031 








默认 情况 下 反 向 代理 是 不 会 转发 请 求 中 的 Host 头 部 的 。 如 果 需 要 转发 ， 那 么 必须 加 上 配 
置 : 








proxy set header Host $host; 





(2) proxy method 
语法 : proxy method method; 
配置 块 http、server、location 


此 配置 项 表示 转发 时 的 协议 方法 名 。 例 如 设置 为 : 





proxy method POST; 





那么 客户 端 发 来 的 GET 请 求 在 转发 时 方法 名 也 会 改 为 POST。 
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(3) proxy hide header 
语法 : proxy hide header the header:; 


配置 块 : http、server、location 





Nginx 会 将 上 游 服 务 器 的 啊 应 转发 给 客户 端 ， 但 默认 不 会 转 帮 以 下 HTTP 头 部 字段 : 
Date、Server、X-Pad 和 X-Accel-*。 使 用 proxy hide _ header 后 可 以 任意 地 指定 哪些 HTTP 头 部 
字段 不 能 被 转发 。 例 如 : 








proxy hide header Cache-Control; 
proxy hide header MicrosoftOfficeWebServer; 





(4) proxy pass header 
语法 : proxy pass header the header:; 
配置 块 : http、server、location 


与 proxy hide header 功 能 相反 ，proxy pass_header 会 将 原来 禁止 转发 的 header 设 置 为 允许 
转发 。 例 如 : 





proxy pass header XxX-Accel-Redirect; 





($5) proxy pass request body 
语法 : proxy pass request body onloff: 
默认 :， proxy pass request body on 
配置 块 : http、server、location 


作用 为 确定 是 否 向 上 游 服务 器 发 送 HTTP 包 体 部 分 。 
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(6) proxy pass request headers 
语法 : proxy pass request headers onlof 
默认 : proxy pass request headers on; 
配置 块 : http、server、location 
作用 为 确定 是 否 转发 HTTP 头 部 。 
(7) proxy redirect 
语法 : proxy redirect[defaultlofflredirect replacement]; 
默认 :， proxy redirect default; 


配置 块 : http、server、location 








当 上 游 服 务 器 返回 的 啊 应 是 重 定向 或 刷新 请 求 〈 如 HTTP 响应 码 是 301 或 者 302) 时 ， 
proxy redirect 可 以 重 设 HTTP 头 部 的 location 或 reffesh 字 段 。 例 如 ， 如 果 上 游 服 务 器 发 出 的 响 
应 是 302 重 定向 请 求 ，location 字 段 的 URI 是 http://localhost:8000/two/some/uri/ ， 那 么 在 下 面 的 





配置 情况 下 ， 实 际 转发 给 客户 端的 location 是 http:// 他 ontendomesome/uri/ 。 





proxy redirect http://localhost:8000/two/ 


http://frontendone; 





这 里 还 可 以 使 用 ngx-http-core-module 提 供 的 变量 来 设置 新 的 location 字 段 。 例 如 : 





proxy redirect http://Localhost:80007 


http://$host:$server port/; 
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也 可 以 省 略 replacement 参 数 中 的 主机 名 部 分 ， 这 时 会 用 虚拟 主机 名 称 来 填充 。 例 如 : 





PrOxY redirect http://localhost:8000/two/one 





使 用 off 参 数 时 ， 将 使 location 或 者 refresh 字 上 段 维持 不 变 。 例 如 : 





proxy redirect off; 





使 用 默认 的 default 参 数 时 ， 会 按照 proxy pass 配 置 项 和 所 属 的 location 配 置 项 重组 发 往 客 
户 问 的 location 头 部 。 例 如 ， 下 面 两 种 配置 效果 是 一 样 的 : 





location one { 
proxy_ pass http://upstream:port/two/ 


proxy redirect default; 
} 
location one { 
proxy pass http://upstream:port/two/ 


proxy _ redirect http://upstream:port/two/one 





(8) proxy next upstream 


语法 : 
proxy next upstream[errorltimeoutlinvalid headerlhttp S00Ihttp 502|http 503lhttp 504|lhttp 404|loff]; 
默认 : proxy_next upstream error timeout; 


配置 块 : http、server、location 


此 配置 项 表示 当 向 一 台 上 游 服务 器 转发 请 求 出 现 错误 时 ， 继 续 换 一 台 上 游 服务 器 处 理 这 
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个 请 求 。 前 面 已 经 说 过 ， 上 游 服务 器 一 旦 开始 发 送 应 答 ，Nginx 反 同人 代理 服务 需 会 立刻 把 应 
答 包 转 友 给 客户 痢 。 因 此 ， 一 旦 Nginx 开 始 同 客户 端 发 送 啊 应 包 ， 之 后 的 过 程 中 大 出 现 错误 
也 是 不 允许 换 下 一 台 上 游 服务 器 继续 处 理 的 。 这 很 好 理解 ， 这 样 才 可 以 更 好 地 保证 客户 端 只 
收 到 来 自 一 个 上 游 服 务 器 的 应 答 。proxy_next_upstream 的 参数 用 来 说 明 在 哪些 情况 下 会 继续 
选择 下 一 人 台 上 游 服 务 器 转发 请 求 。 





eftfror: 当 向 上 游 服务 器 发 起 连接 、 发 送 请 求 、 读 取 响 应 时 出 错 。 

. timeout: 发 送 请 求 或 读 取 响应 时 发 生 超时 。 

.invalid_headerfr: 上 游 服务 器 发 送 的 响应 是 不 合法 的 。 

. http_500: 上 游 服务 器 返回 的 HTTP 响 应 码 是 500。 

. http_502: 上 游 服务 器 返回 的 HTTP 响 应 码 是 502。 

. http_503: 上 游 服务 器 返回 的 HTTP 响 应 码 是 503。 

. http_504: 上 游 服务 器 返回 的 HTTP 响 应 码 是 504。 

. http_404: 上 游 服务 器 返回 的 HTTP 响 应 码 是 404。 

" off: 关闭 proxy_next_upstream 功 能 一 出 错 就 选择 另 一 台 上 游 服务 器 再 次 转发 。 


Nginx 的 反 向 代理 模块 还 提供 了 很 多 种 配置 ， 如 设置 连接 的 超时 时 间 、 临 时 文件 如 何 存 
储 ， 以 及 最 重要 的 如 何 缓存 上 游 服 务 器 响应 等 功能 。 这 些 配置 可 以 通过 阅读 
ngx_http_proxy module 模 块 的 说 明了 解 ， 只 有 深入 地 理解 ， 才 能 实现 一 个 高 性 能 的 反 向 代理 
服务 器 。 本 节 只 是 介绍 反 向 代理 服务 器 的 基本 功能 ， 在 第 12 章 中 我 们 将 会 深入 地 探索 
upstream 机 制 ， 到 那 时 ， 读 者 也 许 会 发 现 ngx_http proxy module 模块 只 是 使 用 upstream 机 制 实 
现 了 反 向 代理 功能 而 已 。 
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6 de 


Nginx 由 少量 的 核心 框架 代码 和 许多 模块 组 成 ， 每 个 模块 剖 有 它 独特 的 功能 。 因 此 ， 读 
者 可 以 通过 得 看 每 个 模块 实现 了 什么 功能 ， 来 了 解 Nginx 可 以 帮 我 们 做 些 什 么 。 


Nginx 的 Wiki 网 站 (http://wiki.nginx.org/Modules ) 上 列 出 了 官方 提供 的 所 有 模块 及 配置 
项 ， 仔 细 观 察 就 会 发 现 ， 这 些 配置 项 的 语法 与 本 章 的 内 容 都 是 很 相近 的 ， 读 者 只 需要 弄 清楚 
模块 说 明 中 每 个 配置 项 的 意义 即 可 。 另 外 ， 网 页 http://wiki.nginx.org/3rdPartyModules 中 列 出 
了 Wiki 上 已 知 的 几 十 个 第 三 方 模块 ， 同 时 读者 还 可 以 从 搜索 引擎 上 搜索 到 更 多 的 第 三 方 模 
块 。 了 解 每 个 模块 的 配置 项 用 法 ， 并 在 Nginx 中 使 用 这 些 模块 ， 可 以 让 Nginx 做 到 更 多 。 





随 着 对 本 书 的 学 习 ， 读 者 会 对 Nginx 模 块 的 设计 思路 有 深入 的 了 解 ， 也 会 渐渐 熟悉 如 何 
编写 一 个 模块 。 如 果 某 个 模块 的 实现 与 你 的 想法 有 出 入 ， 可 以 更 改 这 个 模块 的 源码 ， 实 现 你 
期 望 的 业务 功能 。 如 果 所 有 的 模块 都 没有 你 想 要 的 功能 ， 不 妨 上 自己 重 写 一 个 定制 的 模块 ， 也 
可 以 申请 发 布 到 Nginx 网 站 上 供 大 家 分 享 。 
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第 二 部 分 “如 何 编写 HITP 模 块 
` 第 3 章 ” 开 发 一 个 简单 的 HITP 模 块 
第 4 章 ”配置 、error 日 志和 请 求 上 下 文 
` 第 5 章 ”访问 第 三 方 服务 
` 第 6 章 开发 一 个 简单 的 HITP 过 滤 模 块 


` 第 7 章 ”Nginx 提 供 的 高 级 数据 结构 
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第 3 草 ” 开 及 一 个 简单 的 HITP 模 其 


当 通 过 开发 HTTP 模 块 来 实现 产品 功能 时 ， 是 可 以 完全 享用 Nginx 的 优秀 设计 所 带 来 的 、 
与 官方 模块 相同 的 高 并 发 特性 的 。 不 过 ， 如 何 开 发 一 个 充满 异步 调用 、 无 阻塞 的 HTTP 模 块 
呢 ? 首先 ， 需 要 把 程序 嵌入 到 Nginx 中 ， 也 就 是 说 ， 最 终 编 译 出 的 二 进 制 程序 Nginx 要 包含 我 
们 的 代码 〈 见 3.3 节 ) ; 其次， 这 个 全 新 的 HTTP 模 块 要 能 介入 到 HTTP 请 求 的 处 理 流程 中 ( 具 
体 参见 3.1 节 、3.4 太 、3.5 节 )〉 。 满 足 上 述 两 个 前 提 后 ， 我 们 的 模块 才能 开始 处 理 HTTP 请 
求 ， 但 在 开始 处 理 请 求 前 还 需要 先 了 解 一 些 Nginx 框 架 定义 的 数据 结构 〈 见 3.2 节 ) ， 这 是 后 
面 必须 要 用 到 的 ; 正式 处 理 请 求 时 ， 还 要 可 以 获得 Nginx 框 架 接 收 、 解 析 后 的 用 户 请 求 信 息 
〈 见 3.6 节 ) ;业务 执行 完毕 后 ， 则 要 考虑 发 送 响应 给 用 户 〈 见 3.7 节 ) ， 包 括 将 磁盘 中 的 文 
件 以 HTTP 包 体 的 形式 发 送 给 用 户 《〈 见 3.8 节 ) 。 








本 章 最 后 会 讨论 如 何 用 C++ 语言 来 编写 HTTP 模 块 ， 这 虽然 不 是 Nginx 官 方 倡导 的 方式 ， 
但 C++ 癌 前 羔 容 C 语 言 ， 使 用 C++ 语 言 开 友 的 模块 还 是 可 以 很 容易 地 骨 入 到 Nginx 中 。 本 间 不 
会 深入 探讨 HTTP 模 块 与 Nginx 的 各 个 核心 模块 是 如 何 配 合 工 作 的 ， 而 且 这 部 分 提 到 的 每 个 接 
口 将 只 涉及 用 法 而 不 涉及 实现 原理 ， 在 第 3 部 分 我 们 才 会 进一步 阐述 本 间 提 到 的 许多 接口 是 
如 何 实 现 有 异步 访问 的 。 
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3.1 ”如 何 调 用 HTTP 模 块 


在 开发 HTTP 模 块 前 ， 首 先 需 要 了 解 典型 的 HTTP 模 块 是 如 何 介入 Nginx 处 理 用 户 请 求 流 
程 的 。 图 3-1 是 一 个 简化 的 时 序 图 ， 这 里 省 略 了 许多 异步 调用 ， 和 忽略 了 多 个 不 同 的 HTTP 处 理 
阶段 ， 仅 标识 了 在 一 个 典型 请 求 的 处 理 过 程 中 主要 模块 被 调用 的 流程 ， 以 此 帮助 读者 理解 
HTTP 模 块 如 何 处 理 用 户 请 求 。 完 整 的 流程 将 在 第 11 章 中 详细 介绍 。 
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调用 事件 模块 “| 





根据 配置 文件 交 由 HTTP 


和 
I 
建立 TOP 连接 ; 
Mi 


> 搓 收 却 R 的 HTIP 包 关 
| 
| 
| 
根据 location 配置 调用 HTTP 模块 处 理 请 求 





处 理 请 求 


处 理 后 返回 


POST 请 求 返 回 





所 有 HTTP 过 滤 模 块 返回 


发 送 HTTP 响 应 时 依次 调用 所 有 HTTP 过 小 模块 


根据 处 理 模块 的 逻辑 决定 是 否 执行 POST 请 求 


图 3-1 Neginx HTTP 模 块 调用 的 简化 流程 





根据 配 置 文 件 决定 如 何 处 理 


从 图 3-1 中 看 到 ，worker 进 程 会 在 一 个 for 循 环 语 句 里 反复 调用 事件 模块 检测 网 络 事件 。 


当 事 件 模 块 检测 到 录 个 客户 端 发 起 的 TCP 请 求 时 接收 到 SYN 包 )， 


将 会 为 它 


建 并 TCP 连 


接 ， 成 功 建立 连接 后 根据 nginx.conf 文 件 中 的 配置 会 交 由 HTTP 框 架 处 理 。HTTP 框 架 会 试图 接 
收 完 整 的 HTTP 头 部 ， 并 在 接收 到 完整 的 HTTP 头 部 后 将 请 求 分 发 到 具体 的 HTTP 模 块 中 处 
理 。 这 种 分 发 策略 是 多 样 化 的 ， 其 中 最 常见 的 是 根据 请 Re conf 里 location 配 置 项 








ee 人 S| 





第 10 章 中 会 
站 


B66 0 } 友 


策略 ) 。HTTP 模 块 在 处 理 请 求 的 结束 时 ， 大 多 会 向 客户 端 发 送 啊 应 ， 此 时 会 自动 地 依次 调 

用 所 有 的 HITP 过 滤 模 块 ， 每 个 过 滤 模 块 可 以 根据 配置 文件 决定 自己 的 行为 。 例 如 ，gzip 过 滤 
模块 根据 配置 文件 中 的 gzip onloff 来 决定 是 否 压 缩 响应 。HTTP 处 理 模块 在 返回 时 会 将 控制 权 

交还 给 HTTP 框 架 ， 如 果 在 返回 前 设置 了 subrequest， 那 么 HTTP 框 架 还 会 继续 异步 地 调用 适合 
的 HITP 模 块 处 理子 请 求 。 





开发 HTTP 模 块 时 ， 首 先 要 注意 的 就 是 HTTP 框 架 到 具体 的 HTTP 模 块 间 数据 流 的 传递 ， 
以 及 开发 的 HTTP 模 块 如 何 与 诸多 的 过 滤 模 块 协 同 工 作 (第 10 章 、 第 11 章 会 详细 介绍 HTTP 框 
架 ) 。 下 面 正式 进入 HTTP 模 块 的 开发 环节 。 
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3.2 ”准备 工作 








Nginx 模 块 需要 使 用 C〈 或 者 C++) 语言 编写 代码 来 实现 ， 每 个 模块 都 要 有 自己 的 名 字 。 
按照 Nginx 约 定 俗 成 的 命名 规则 ， 我 们 把 第 一 个 HTTP 模 块 命名 为 ngx http mytest module。 由 
于 第 一 个 模块 非常 简单 ， 一 个 C 源 文件 就 可 以 完成 ， 所 以 这 里 按照 官方 惯例 ， 将 唯一 的 源 代 
码 文件 命名 为 ngx http mytest module.c。 








实际 上 上， 我们 还 需要 定义 一 个 名 称 ， 以 便 在 编译 前 的 configure 命 令 执行 时 显示 是 个 执行 
成 功 〈 即 configure 脚 本 执行 时 的 ngx addon _ name 变量) 。 为 方便 理解 ， 仍 然 使 用 同一 个 模块 
名 来 表示 ， 如 ngx_http_ mytest module。 


为 了 让 HTTP 模 块 正 滑 工 作 ， 首 先 需 要 把 它 编 译 进 Nginx 〈3.3 节 会 探讨 编译 新 增 模块 的 两 
种 方式 ) 。 其 次 需要 设 定 模块 如 何在 运行 中 生效 ， 比 如 在 图 3-1 描 述 的 典型 方式 中 ， 配 置 文 
件 中 的 location 块 决定 了 匹配 东 种 URI 的 请 求 将 会 由 相应 的 HITP 模 块 处 理 ， 因 此 ， 运 行 时 
HTTP 框 架 会 在 接收 完毕 HTTP 请 求 的 头 部 后 ， 将 请 求 的 URI 与 配置 文件 中 的 所 有 location 进 行 
匹配 《事实 上 会 优先 匹配 虚拟 主机 ， 第 11 章 会 详细 说 明 访 流程) ， 匹 配 后 再 根据 location{} 内 
的 配置 项 选择 HITTP 模 块 来 调用 。 这 是 一 种 最 典型 的 HTTP 模块 调 用 方式 。3.4 节 将 解释 HITP 
模块 定义 租 入 方式 时 用 到 的 数据 结构 ，3.5 节 将 定义 我 们 的 第 一 个 HTTP 模块 ，3.6 节 中 介绍 如 
何 使 用 上 述 模块 调用 方式 来 处 理 请 求 。 








既然 有 典型 的 调用 方式 ， 自 然 也 有 非典 型 的 调用 方式 ， 比 如 ngx_http_access_module 模 
块 ， 它 是 根据 下地 址 决定 某 个 客户 端 是 否 可 以 访问 服务 的 ， 因 此 ， 这 个 模块 需要 在 
NGX HTTP ACCESS _ PHASE 阶段 〈 在 第 10 章 中 会 详 述 HTTP 框 架 定 义 的 11 个 阶段 ) 生效 ， 
它 会 比 本 章 介绍 的 mytest 模 块 更 早 地 介入 请 求 的 处 理 中 ， 同 时 它 的 流程 与 图 3-1 中 的 不 同 ， 它 
可 以 对 所 有 请 求 产生 作用 。 也 就 是 说 ， 任 何 HTTP 请 求 都 会 调用 ngx_http_access_module 模 块 
处 理 ， 只 是 该 模块 会 根据 它 感 兴趣 的 配置 项 及 所 在 的 配置 块 来 决定 行为 方式 ， 这 与 mytest 模 
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块 不 同 ， 在 mytest 模 块 中 ， 只 有 在 配置 了 location/uri{mytest;} 后 ，HTTP 框 架 才 会 在 某 个 请 求 
匹配 了 /uri 后 调用 它 处 理 请 求 。 如 果 某 个 匹配 了 URI 请 求 的 location 中 没有 配置 mytest 配 置 项 ， 
mytest 模 块 依然 是 不 会 被 调用 的 。 





为 了 做 到 路 平台 ，Nginx 定 义 、 封 装 了 一 些 基本 的 数据 结构 。 由 于 Nginx 对 内 存 分 配 比 
较 “ 音 调 ”〈 只 有 保证 低 内 存 消耗 ， 才 可 能 实现 十 万 甚 全 百 万 级 别 的 同时 并 发 连接 数 ) ， 所 以 
这 些 Nginx 数 据 结构 天 生 都 是 尽 可 能 少 占 用 内 存 。 下 面 介 绍 本 章 中 将 要 用 到 的 Nginx 定 义 的 几 
个 基本 数据 结构 和 方法 ， 在 第 7 章 还 会 介绍 一 些 复 洒 的 容器 ， 读 者 可 以 从 中 体会 到 如 何 才能 
有 效 地 利用 内 存 。 











3.2.1 整 型 的 封装 


Nginx 使 用 ngx int t 封 装 有 符号 整 型 ， 使 用 ngx vint t 封 装 无 符号 整 型 。Nginx 各 模块 的 变 
量 定义 都 是 如 此 使 用 的 ， 建 议 读 者 沿用 Nginx 的 习惯 ， 以 此 蔡 代 intfiunsinged int。 


在 Linux 平 台 下 ，Nginx 对 ngx int tIngx uint t 的 定义 如 下 : 


typedef intptr t ngx int t; typedef uintptr t ngx uint t; 


3.2.2 ”ngx_str {t 数 据 结构 


在 Nginx 的 领域 中 ，ngx_str_t 结 构 就 是 字符 串 。ngx_str_t 的 定义 如 下 : 





typedef struct { 
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ngx_str_ t 只 有 两 个 成 员 ， 其 中 data 指 针 指 向 字符 串 起 始 地 址 ，len 表 示 字 符 串 的 有 效 长 
度 。 注 意 ，ngx_str_t 的 data 成 员 指向 的 并 不 是 普通 的 字符 串 ， 因 为 这 段 字符 串 未 必 会 以 WO' 作 
为 结尾 ， 所 以 使 用 时 必须 根据 长 度 len 来 使 用 data 成 员 。 例 如 ， 在 3.7.2 节 中 ， 我 们 会 看 到 r- 
>method _ name 就 是 一 个 ngx_str_t 类 型 的 变量 ， 比 较 method_name 时 必须 如 下 这 样 使 用 : 








if (0 == ngx strncmp ( 


r->method name.data, 


r->method name.1len) 





这 里 ，ngx_strncemp 其 实 束 是 strncemp 岗 数 ， 为 了 跨 平 台 Nginx 习 惯性 地 对 其 进行 了 名 称 上 
的 封装 ， 下 面 看 一 下 它 的 定义 : 





#define ngx strncmp(sl, s2, n) strncmp ( (Const char *) sl, (const char *) s2, n) 








任何 试图 将 ngx_str_t 的 data 成 员 当 做 字符 串 来 使 用 的 情况 ， 都 可 能 导致 内 存 越界 ! Nginx 
使 用 ngx_str_t 可 以 有 效 地 降低 内 存 使 用 量 。 例 如 ， 用 户 请 求 “GET/testa=1 http/1.1No" 存 储 到 内 
存 地 址 0x1d0b0110 上 ， 这 时 只 需要 把 r->method name 设 置 为 {len=3,data=0x1d0b0110} 就 可 以 表 
示 方 法 名 “GET"， 而 不 需要 单独 为 method name 再 分 配 内 存 宛 余 的 存储 字符 串 。 





3.2.3 ngx list {t 数 据 结构 
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ngx_list_ t 是 Nginx 封 装 的 链表 容器 ， 它 在 Nginx 中 使 用 得 很 频繁 ， 例 如 HTTP 的 头 部 就 是 用 
ngx_list t 来 存储 的 。 当 然 ，C 语 言 封装 的 链表 没有 C++ 或 Java 等 面向 对 象 语 言 那么 容易 理解 。 
先 看 一 下 ngx_list t 相 关 成 员 的 定义 : 











typedef struct ngx list part s ngx list part t; Struct ngx list part s { 


void *elts; 





ngx uint t nelts; 


ngx list part t *next; 


typedef struct { 


ngx list part. tLast> 


ngx list part t part; 


size t size; 
ngx uint t nalloc; 
ngx pool t *DOOL; 

} ngx list t; 





ngx_list_t 描 述 整 个 链表 ， 而 ngx_list_part t 只 描述 链表 的 一 个 元 素 。 这 里 要 注意 的 是 ， 
ngx_list t 不 是 一 个 单纯 的 链表 ， 为 了 便于 理解 ， 我 们 姑且 称 它 为 存储 数组 的 链表 ， 什 么 意思 
呢 ? 抽象 地 说 ， 就 是 每 个 链表 元 素 ngx_list part { 又 是 一 个 数组 ， 拥 有 连续 的 内 存 ， 它 既 依赖 
于 ngx_list t 里 的 size 和 nalloc 来 表示 数组 的 容量 ， 同 时 又 依靠 每 个 ngx_list_part 成员 中 的 nelts 
来 表示 数组 当前 已 使 用 了 多 少 容量 。 因 此 ，ngx list t 是 一 个 链表 容器 ， 而 链表 中 的 元 素 又 是 


于 人 得 中 由 OF oP EO 下巴 





够 容纳 的 元 素数 量 由 ngx_list_part t 激 组 元 素 的 个 数 与 每 个 数组 所 能 容纳 的 元 素 相 乘 得 到 。 
这 样 设 计 有 什么 好 处 呢 ? 
` 链表 中 存储 的 元 素 是 灵活 的 ， 它 可 以 是 任何 一 种 数据 结构 。 
. 链表 元 素 需 要 占用 的 内 存 由 ngx list t 管 理 ， 它 已 经 通过 数组 分 配 好 了 。 


-小 块 的 内 存 使 用 链表 访问 效率 是 低下 的 ， 使 用 数组 通过 偏 移 量 来 直接 访问 内 存 则 要 高 


效 得 多 。 





下 面 详 述 每 个 成 员 的 音义 。 
(1) ngx list t 
- batt: 链表 的 首 个 数组 元 素 。 
.last: 指向 链表 的 最 后 一 个 数组 元 素 。 


. size: 前 面 讲 过 ， 链 表 中 的 每 个 ngx_list_part_t 元 素 都 是 一 个 数组 。 因 为 数组 存储 的 是 
某 种 类 型 的 数据 结构 ， 且 ngx_list_t 是 非常 灵活 的 数据 结构 ， 所 以 它 不 会 限制 存储 什么 样 的 数 
据 ， 只 是 通过 size 限 制 每 一 个 数组 元 素 的 占用 的 空间 大 小 ， 也 就 是 用 户 要 存储 的 一 个 数据 所 
节 数 必须 小 于 或 等 于 size。 


. nalloc: 链表 的 数组 元 素 一 旦 分 配 后 是 不 可 更 改 的 。nalloc 表 示 每 个 ngx_list_part_t 数 组 


的 容量 ， 即 最 多 可 存储 多 少 个 数据 。 


` pool: 链表 中 管理 内 存 分 配 的 内 存 池 对 象 。 用 户 要 存放 的 数据 占用 的 内 存 都 是 由 pool 


分 配 的 ， 下 文中 会 详细 介绍 。 
(2) ngx list part t 


NNn httpo://ww linuxorobe. con 





.elts: 指向 数组 的 起 始 地 址 。 


.nelts: 表示 数组 中 己 经 使 用 了 多 少 个 元 素 。 当 然 ，nelts 必 须 小 于 ngx_list_t 结 构 体 中 的 


nalloc。 
next: 下 一 个 链表 元 素 ngx_list_part_t 的 地 址 。 


事实 上 ，ngx list t 中 的 所 有 数据 都 是 由 ngx_pool t 类 型 的 pool 内 存 池 分 配 的 ， 它 们 通常 都 
是 连续 的 内 存 〈 在 由 一 个 pool 内 存 池 分 配 的 情况 下 ) 。 下 面 以 图 3-2 为 例 来 看 一 下 ngx list t 的 
内 存 分 布 情况 。 





ngx_list_1 





Negx_list_part_t (1) 





Nex_list_part_t (2) 


Ngx_list_part_t (3) 











本 段 内 存 人 存储 本 段 内 存 存 储 本 段 内 存 存 储 本 段 内 存 存储 
ngx_list_1 nex_list nex_list nex_list 
结构 part_t (1) part_t (2) part_t (3) 


结构 结构 结构 
图 3-2 ngx_list_t 的 内 存 分 布 
图 3-2 中 是 由 3 个 ngx_list_part t 数 组 元 素 组 成 的 ngx_list 链表 可 能 拥有 的 一 种 内 存 分 布 结 


构 ， 读 者 可 以 从 这 种 较为 常见 的 内 存 分 布 中 看 到 ngx list t 链 表 的 用 法 。 这 里 ，pool 内 存 池 为 
口 由 掉 岂 有 所 和 所 掉 由 http' /wNv inuxorobe, con 





其 分 配 了 连续 的 内 存 ， 最 前 端 内 存 存 储 的 是 ngx_list_t 结 构 中 的 成 员 ， 紧 接着 是 第 一 个 

ngx list part t 结 构 占 用 的 内 存 ， 然 后 是 ngx_ list part t 结 构 指向 的 数组 ， 它 们 一 共 占 用 
size*nalloc 字 节 ， 表 示 数 组 中 拥有 nalloc 个 大 小 为 size 的 元 素 。 其 后 面 是 第 2 个 ngx_list_part t 结 
构 以 及 它 所 指向 的 数组 ， 依 此 类 推 。 


对 于 链表 ，Nsginx 提 供 的 接口 包括 : ngx list_create 接 口 用 于 创建 新 的 链表 ，ngx list_ init 
接口 用 于 初始 化 一 个 已 有 的 链表 ，nsx list push 接 口 用 于 添加 新 的 元 素 ， 如 下 所 示 : 





ngx list t ngx list create(ngx pool t pool, ngx uint t n size t size); static ngx _ inline ngx int t 





ngx list init(ngx list t list, ngx pool t pool, ngx uint t n, size t size); void ngx list push(ngx list t list) 








调用 ngx_list_create 创 建 元 素 时 ，pool 参 数 是 内 存 池 对 象 “参见 3.7.2 节 ) ，size 是 每 个 元 
素 的 大 小 ，n 是 每 个 链表 数组 可 容纳 元 素 的 个 数 ( 相 当 于 ngx_list t 结 构 中 的 nalloc 成 员 )。 
ngx_list_create 返 回 新 创建 的 链表 地 址 ， 如 果 创 建 失败 ， 则 返回 NULL 空 指针 。ngx_list_create 
被 调用 后 至 少 会 创建 一 个 数组 (不 会 创建 空 链 表 ) ， 其 中 包含 n 个 大 小 为 size 字 节 的 连续 内 存 
块 ， 也 就 是 ngx list t 结 构 中 的 part 成 员 。 





下 和 面 看 一 个 简单 的 例子 ， 我 们 首先 建立 一 个 链表 ， 它 存储 的 元 素 是 ngx_str t， 其 中 每 个 
链表 数组 中 存储 4 个 元 素 ， 代 码 如 下 所 示 : 





ngx list tx testlist = ngx list create(r->pool, 4,sizeof (ngx str t)); if (testlist == NULL) { 


return NGX ERROR; 














ngx_list_init 的 使 用 方法 与 ngx_list_create 非 常 类 似 ， 需 要 注意 的 是 ， 这 时 链表 数据 结构 已 
经 创建 好 了 ， 奉 ngx_list_init 返 回 NGX_OK， 则 表示 初始 化 成 功 ， 阁 返回 NGX_ERROR， 则 表 


示 失 败 。 
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调用 ngx list_push 表 示 添 加 新 的 元 素 ， 传 入 的 参数 是 ngx_list t 链 表 。 正 常情 况 下 ， 返 回 
的 是 新 分 配 的 元 素 首 地 址 。 如 果 返 回 NULL 空 指针 ， 则 表示 添加 失败 。 在 使 用 它 时 通常 先 调 
用 ngx 1list push 得 到 返回 的 元 素 地 址 ， 再 对 返回 的 地 址 进行 赋值 。 例 如 : 





ngx str t* str = ngx list push(testlist); if (str == NULL) { 


return NGX ERROR; 





str->len= sizeof ("Hello world"); 





str->data = "Hello world"; 











避 历 链表 时 Nginx 没 有 提供 相应 的 接口 ， 实 际 上 也 不 需要 。 我 们 可 以 用 以 下 方法 所 历 链 
表 中 的 元 素 : 





// part 用 于 指向 链表 中 的 每 一 个 


ngx list part 七 数组 


ngx list part tx part = &testlist.part; // 根据 链表 中 的 数据 类 型 ， 把 数组 里 的 


elts 转 化 为 该 类 型 使 用 


ng Str t* .str = Part=>eltss 
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// i 表示 元 素 在 链表 的 每 个 


ngx 1ist part 七 数组 里 的 序号 


for (i = 07 /* void */; f+) { 
if (i >= part->nelts) { 
if (part->next == NULL) { 


// 如 果 某 个 


ngx 1ist part 七 数组 的 


next 指 针 为 空 ， 


// 则 说 明 已 经 遍历 完 链表 


break; 


/7 访问 下 一 个 


ngx list part t 
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part = part->next; 


str = part->elts; 


// 将 


i 序号 置 为 





0 ， 准 备 重新 访问 下 一 个 数组 


// 这 里 可 以 很 方便 地 取 到 当前 遍历 到 的 链表 元 素 


Printf("1List element: %*s\n",str[i].len, str[i].data); } 





3.2.4 ngx table elt 堵 据 结构 


ngx_table_elt 坝 据 结构 如 下 所 示 : 





typedef struct { 
ngx uint t hash; 


ngx_ str 七 key; 
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ngx_ str t value; 


u char *lowcase key; 


} ngx table elt t; 





可 以 看 到 ，ngx table elt t 就 是 一 个 key/value 对 ，ngx_str t 类 型 的 key、value 成 员 分 别 存 储 
的 是 名 字 、 值 字符 串 。hash 成 员 表 明 ngx_table_elt t 也 可 以 是 某 个 散 列表 数据 结构 (ngx_hash t 
类 型 ) 中 的 成 员 。ngx_uint 类 型 的 hash 成 员 可 以 在 ngx_hash t 中 更 快 地 找到 相同 key 的 
ngx table_ elt 坝 据 。lowcase_ key 指向 的 是 全 小 写 的 key 字 符 串 。 





显而易见 ，ngx_table_elt t 是 为 HTTP 尖 部 “ 量 映 订 制 "的 ， 其 中 key 存 储 尖 部 名 称 〈 如 
Content-Length)，value 存 储 对 应 的 值 ( 如 “1024”) ，lowcase_ key 是 为 了 忽略 HTTP 头 部 名 称 
的 大 小 写 〈 例 如 ， 有 些 客户 端 发 来 的 HTTP 请 求 头 部 是 content-length，Nginx 希 望 它 与 大 小 写 
敏感 的 Content-Length 做 相同 处 理 ， 有 了 全 小 写 的 lowcase_key 成 员 后 就 可 以 快速 达成 目的 
了 ) ，hash 用 于 快速 检索 头 部 〈 它 的 用 法 在 3.6.3 节 中 进行 详 述 ) 。 











3.2.5 _ ngx buf 堵 [ 据 结构 





绥 冲 区 ngx_buf { 是 Nginx 处 理 大 数据 的 关键 数据 结构 ， 它 既 应 用 于 内 存 数据 也 应 用 于 破 
盘 数据 。 下 面 主要 介绍 ngx_buf t 结 构 体 本 里， 而 描述 磁 副 文件 的 ngx_file_t 结 构 体 则 在 3.8.1 市 
中 说 明 。 下 面 来 看 一 下 相关 代码 : 











typedef struct ngx buf s ngx buf t; typedef void * ngx buf tag t; struct ngx buf s { 





/*pos 通 常 是 用 来 告诉 使 用 者 本 次 应 该 从 


pos 这 个 位 置 开始 处 理 内 存 中 的 数据 ， 这 样 设置 是 因为 同一 个 
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ngx_buf 七 可 能 被 多 次 反复 处 理 。 当 然 ， 


Pos 的 含义 是 由 使 用 它 的 模块 定义 的 
*/ 
u char *pOS; 


/*1last 通 常 表示 有 效 的 内 容 到 此 为 止 ， 注 意 ， 


pos 与 


last 之 间 的 内 存 是 希望 


nginx 处 理 的 内 容 
u char *last; 


A/* 处 理 交 件 时 ; 


file pos 与 


file_last 的 含义 与 处 理 内 存 时 的 
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last 相 同 ， 


file_pos 表 示 将 要 处 理 的 文件 位 置 ， 


file last 表 示 截 止 的 文件 位 置 


4 


GE 荡 file pos; 
off 七 file last; 
// 如 果 


ngx_buf 七 缓冲 区 用 于 内 存 ， 那 么 


start 指 向 这 段 内 存 的 起 始 地 址 


UU Char “estarty 


start 成 员 对 应 ， 指 向 缓冲 区 内 存 的 末尾 
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i Ghar *end; 


/x* 表 示 当 前 缓冲 区 的 类 型 ， 例 如 由 哪个 模块 使 用 就 指向 这 个 模块 


ngx moqule 芋 变 量 的 地 址 


* 


ngx buf tag t tag; 


// 引用 的 文件 


ngx file t *file; 


/* 当 前 缓冲 区 的 影子 缓冲 区 ， 该 成 员 很 少 用 到 ， 仅 仅 在 


12.8 节 描述 的 使 用 缓冲 区 转发 上 游 服务 器 的 响应 时 才 使 用 了 


shadow 成 员 ， 这 是 因为 


Nginx 太 节约 内 存 了 ， 分 配 一 块 内 存 并 使 用 


ngx_buf_t 表 示 接 收 到 的 上 游 服务 器 响应 后 ， 在 向 下 游客 户 端 转发 时 可 能 会 把 这 块 内 存 存 储 到 文件 中 ， 也 可 能 直接 向 下 游 发 送 ， 此 时 


Nginx 绝 不 会 重新 复制 一 份 内 存 用 于 新 的 目的 ， 而 是 再 次 建立 一 个 
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ngx_buf 七 结构 体 指向 原 内 存 ， 这 样 多 个 

ngx_buf_t 结 构 体 指向 了 同一 块 内 存 ， 它 们 之 间 的 关系 就 通过 

shaqow 成 员 来 引用 。 这 种 设计 过 于 复杂 ， 通 常 不 建议 使 用 
ngx buf 七 *shadow; 


// 临时 内 存 标志 位 ， 为 


1 时 表示 数据 在 内 存 中 且 这 段 内 存 可 以 修改 


unsigned temporary:1; 


// 标志 位 ， 为 


1 时 表示 数据 在 内 存 中 且 这 段 内 存 不 可 以 被 修改 


unsigned memory:1; 


// 标志 位 ， 为 


1 时 表示 这 段 内 存 是 用 
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mmap 系 统 调用 映射 过 来 的 ， 不 可 以 被 修改 


unsigned mmap:1; 
// 标志 位 ， 为 
1 时 表示 可 回收 
unsigned recycled:1; 
// 标志 位 ， 为 


1 时 表示 这 上 段 缓冲 区 处 理 的 是 文件 而 不 是 内 存 


unsigned in 得 工 二 人 于 学 


// 标志 位 ， 为 


1 时 表示 需要 执行 


flush 操 作 
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unsigned 下 二 站 号 His 二 3 


/* 标 志 位 ， 对 于 操作 这 块 缓冲 区 时 是 否 使 用 同步 方式 ， 需 谨慎 考虑 ， 这 可 能 会 阻塞 


Nginx 进 程 ， 


Nginx 中 所 有 操作 几乎 都 是 异步 的 ， 这 是 它 支持 高 并 发 的 关键 。 有 些 框架 代码 在 


Sync 为 


1 时 可 能 会 有 阻塞 的 方式 进行 


I/O 操 作 ， 它 的 意义 视 使 用 它 的 


Nginx 模 块 而 定 
*/ 
unsigned sync:1; 


/* 标 志 位 ， 表 示 是 否 是 最 后 一 块 缓冲 区 ， 因 为 


ngx buf 七 可 以 由 


口 由 掉 所 有 所 和 所 掉 由 http' /wNv inuxorobe. con 





ngx chain 七 链表 串联 起 来 ， 因 此 ， 当 
last buf 为 


1 时 ， 表 示 当 前 是 最 后 一 块 待 处 理 的 缓冲 区 


4 
unsigned last buf:1; 


// 标志 位 ， 表 示 是 否 是 


ngx chain 七 中 的 最 后 一 块 缓冲 区 


unsigned last in chain:1; 


/* 标 志 位 ， 表 示 是 否 是 最 后 一 个 影子 缓冲 区 ， 与 


shadow 域 配合 使 用 。 通 常 不 建议 使 用 它 
4 
unsigned last shadow:1; 


// 标志 位 ， 表 示 当 前 缓冲 区 是 否 属于 临时 文件 


unsigned temp file:1; 
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关于 使 用 ngx_buf t 的 案例 参见 3.7.2 节 。ngx_buf 十 一 种 基本 数据 结构 ， 本 质 上 它 提供 的 
仅仅 是 一 些 指针 成 员 和 标志 位 。 对 于 HTTP 模 块 来 说 ， 需 要 注意 HTTP 框架 、 事 件 框架 是 如 何 
设置 和 使 用 pos、last 等 指针 以 及 如 何 处 理 这 些 标志 位 的 ， 上 述说 明 只 是 最 常见 的 用 法 。〔 如 
果 我 们 自 定义 一 个 ngx_buf t 结 构 体 ， 不 应 当 受 限于 上 述 用 法 ， 而 应 该 根据 业务 需求 自行 定 
义 。 例 如 ， 在 13.7 节 中 用 一 个 ngx_buf t 组 种 区 转发 上 下 游 TCP 流 时 ，pos 会 指 同 将 要 发 送 到 下 
游 的 TCP 流 起 始 地 址 ， 而 last 会 指向 预备 接收 上 游 TCP 流 的 缓冲 区 起 始 地 址 。) 








3.2.6 ”ngx _chain {t 数 据 结构 


ngx_chain t 是 与 ngx buf t 配 合 使 用 的 链表 数据 结构 ， 下 面 看 一 下 它 的 定义 : 





typedef struct ngx chain s ngx chain t; struct ngx chain s { 


ngx buf t *buf; 


ngx chain t *next; 





buf 指 向 当前 的 ngx_buf t 绥 冲 区 ，next 则 用 来 指 问 下 一 个 ngx_chain t。 如 果 这 是 最 后 一 个 
ngx_chain t， 则 需要 把 next 置 为 NULL。 


在 向 用 户 发 送 HTTP 包 体 时 ， 就 要 传 入 ngx_chain t 链 表 对 象 ， 注 意 ， 如 果 是 最 后 一 个 
ngx_chain t， 那 么 必须 将 next 置 为 NULL， 人 否则 永远 不 会 发 送 成 功 ， 而 且 这 个 请 求 将 一 直 不 会 


结束 (Nginx 框 染 的 要 求 〉。 
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3.3 如何 将 自己 的 HITP 模 块 编 译 进 Nginx 








Nginx 提 供 了 一 种 简单 的 方式 将 第 三 方 的 模块 编译 到 Nginx 中 。 首 先 把 源 代码 文件 全 部 放 
到 一 个 目录 下 ， 同 时 在 该 目录 中 编写 一 个 文件 用 于 通知 Nginx 如 何 编译 本 模块 ， 这 个 文件 名 
必须 为 config。 它 的 格式 将 在 3.3.1 节 中 说 明 。 

这 样 ， 只 要 在 configure 脚 本 执行 时 加 入 参数 --add-module=PATH (PATH 就 是 上 面 我 们 给 
定 的 源 代码 、config 文 件 的 保存 目录 〉 ， 就 可 以 在 执行 正常 编译 安装 流程 时 完成 Nginx 编 译 工 
作 。 





有 时 ，Nginx 提 供 的 这 种 方式 可 能 无 法 满足 我 们 的 需求 ， 其 实 ， 在 执行 完 configure 脚 本 后 
Nginx 会 生成 objs/Makefile 和 objs/ngx_modules.c 文 件 ， 完 全 可 以 自己 去 修改 这 两 个 文件 ， 这 是 
一 种 更 强大 也 复杂 得 多 的 方法 ， 我 们 将 在 3.3.3 节 中 说 明 如 何 直接 修改 它们 。 





3.3.1 config 文 件 的 写法 


config 文 件 其 实 是 一 个 可 执行 的 Shell 脚 本 。 如 果 只 想 开 发 一 个 HTTP 模 块 ， 那 么 config 文 
件 中 需要 定义 以 下 3 个 变量 : 
ngx_addon_name: 仅 在 configute 执 行 时 使 用 ， 一 般 设 置 为 模块 名 称 。 
. HITP MODULES: 保存 所 有 的 HTTP 模 块 名 称 ， 每 个 HTTP 模 块 间 由 空格 符 相 连 。 在 
重新 设置 HIIP_MODULES 变 量 时 ， 不 要 直接 履 盖 它 ， 因 为 configure 调 用 到 自 定义 的 config 脚 
本 前 ， 已 经 将 各 个 HTTP 模 块 设置 到 HTTP_MODULES 变 量 中 了 ， 因 此 ， 要 像 如 下 这 样 设 


置 : 





"$HTTP MODULES ngx http mytest module" 
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- NGX_ADDON_SRCS: 用 于 指定 新 增 模 块 的 源 代 码 ， 多 个 待 编译 的 源 代码 间 以 空格 
符 相 连 。 注 意 ， 在 设置 NGX_ADDON_SRCS 时 可 以 使 用 $ngx_addon_dir 变 量 ， 它 等 价 于 


configure 执 行 时 --add-module=PATH 的 PATH 参 数 。 


因此 ， 对 于 mytest 模 块 ， 可 以 这 样 编写 config 文 件 : 





ngx addon name=ngx http mytest module 
HTTP MODULES="$HTTP MODULES ngx http mytest module" 
NGX ADDON SRCS="$NGX ADDON SRCS S$ngx addon dir/ngx http mytest module.c" 











@ 注意 以 上 3 个 变量 并 不 是 唯一 可 以 在 config 文 件 中 自 定 义 的 部 分 。 如 果 我 们 不 是 开 
发 HTTP 模 块 ， 而 是 开发 一 个 HTTP 过 滤 模 块 ， 那 么 就 要 用 HTTP_FILTER_MODULES 替 代 上 


面 的 HTIP MODULES 变 量 。 事 实 上 ， 包 括 $CORE_ MODULES、$EVENT_MODULES、 





$HTTP_MODULES、 $HTTP_FILTER_MODULES、$HTIP_HEADERS_FILTER_MODULE 等 
模块 变量 都 可 以 重 定义 ， 它 们 分 别 对 应 着 Nginx 的 核心 模块 、 事 件 模块 、HTTP 模 块 、HTTP 
过 滤 模 块 、HTTP 头 部 过 滤 模 块 。 除 了 NGX_ADDON_SRCS 变 量 ， 或 许 还 有 一 个 变量 我 们 会 
用 到 ， 即 $WNGX_ADDON_DEPS 变 量 ， 它 指定 了 模块 依赖 的 路 径 ， 同 样 可 以 在 config 中 设 


置 。 


3.3.2 ”利用 configure 脚 本 将 定制 的 模块 加 入 到 Nginx 中 


在 1.6 节 提 到 的 configure 执 行 流程 中 ， 其 中 有 两 行 脚本 负责 将 第 三 方 模块 加 入 到 Nginx 
中 ， 如 下 所 示 。 





. auto/modules 
. auto/make 





下 面 完 整地 解释 一 下 configure 脚 本 是 如 何 与 3.3.1 节 中 提 到 的 config 文 件 配合 起 来 把 定制 的 
第 三 方 模块 加 入 到 Nginx 中 的 。 
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configure 中 ， 通 过 auto/options 脚 本 设置 了 NGX _ ADDONS 变 量 : 





--add-module=*) NGX ADDONS="$NGX ADDONS S$value" 





在 configure 命 令 执行 到 auto/modules 脚 本 时 ， 将 在 生成 的 ngx_modules.c 文 件 中 加 入 定制 的 
第 三 方 模块 。 





if test -n "S$NGX ADDONS"; then 
echo configuring additional modules 
for ngx addon dir in $NGX ADDONS 
do 
echo "adding module in Sngx addon dir" 
if test -f $ngx addon dir/config; then 
# 在 这 里 执行 自 定义 的 


config 脚 本 


. $ngx addon dir/config 
echo " + $ngx addon name was configured" 

else 
echo "$0: error: no Sngx addon dir/config was found" 
exit 1 

£1i 

done 
£1i 














可 以 看 到 ，$NGX_ADDONS 可 以 包含 多 个 目录 ， 对 于 每 个 日 录 ， 如 果 其 中 存在 config 文 
件 就 会 执行 ， 也 就 是 说 ， 在 config 中 重新 定义 的 变量 都 会 生效 。 之 后 ，auto/modules 脚 本 开始 
创建 ngx_modules.c 文 件 ， 这 个 文件 的 关键 点 就 是 定义 了 ngx_module_t*ngx_modules[] 数 组 ， 
个 数组 存储 了 Nginx 中 的 所 有 模块 。Nginx 在 初始 化 、 处 理 请 求 时 ， 都 会 循环 访问 ngx_modules 
数组 ， 确 定 该 用 哪 一 个 模块 来 处 理 。 下 面 来 看 一 下 auto/modules 是 如 何 生成 数组 的 ， 代 码 如 
下 所 未 

















modules="$CORE MODULES SEVENT MODULES" 
if [ $USE OPENSSL = YES ]; then 
modules="$modules SOPENSSL MODULE" 
CORE DEPS="$CORE DEPS S$OPENSSL DEPS" 
CORE SRCS="$CORE SRCS $OPENSSL SRCS" 










































































































































































£1i 
££ [| SHTTP = YES 1]» then 
modules="$modules $HTTP MODULES $HTTP FILTER MODULES \ 
SHTTP HEADERS FILTER MODULE \ 
$HTTP_ AUX FILTER MODULES \ 
$SHTTP COPY FILTER MODULE \ 
SHTTP RANGE BODY FILTER MODULE \ 
TTP_NOT_MODIEIEP_FITTPR MODULE" a 
:as 上 apaosl Ft hss ees htt op: / / Ww | i nuxporobe. con 








fi 





首先 ，auto/modules 会 按 顺序 生成 modules 变 量 。 注 意 ， 这 里 的 $HTTP MODULES 等 已 经 
在 config 文 件 中 重 定 义 了 。 这 时 ，modules 变 量 是 包含 所 有 模块 的 。 然 后 ， 开 始 生 成 
ngx_modules.c 文 件 : 








cat << END > $NGX MODULES C 
include <ngx config.h> 

include <ngx core.h> 

SNGX_PRAGMA 


























END 
for mod in Smodqules 
do 

echo "extern ngx module t $mod;" >> $NGX MODULES C 
done 
echo >> $NGX MODULES C 
echo "ngx module 七 *ngx modules[] = {" >> $NGX MODULES C 
for mod in $modules 
do 

# 向 


ngx modqules 数 组 里 添加 

















Nginx 模 块 
echo " &$mod," >> $NGX MODULES C 
done 
cat << END >> $NGX MODULES C 
NULL 
}; 
END 








这 样 就 已 经 确定 了 Nginx 在 运行 时 会 调用 上 自 定 义 的 模块 ， 而 auto/make 脚 本 负责 把 相关 模 
块 编译 进 Nginx。 


在 Makefile 中 生成 编译 第 三 方 模块 的 源 代码 如 下 : 





if test -n "SNGX ADDON SRCS"; then 
ngx cc="\$(CC) $ngx compile opt \$ (CFLAGS) Sngx use pch \$ (ALL INCS)" 
for ngx src in SNGX ADDON SRCS 
do 
ngx obj="addon/ basename \ dirname S$ngx src\  " 
ngx obj= echo $ngx obj/\ basename Sngx SrcN AN 
| sed -e "s/\// $ngx regex dirsep/g". 
ngx obj= echo $ngx obj \ 
| sed -e 
"Ss#^\(.*\.\)cpp\\$#$ngx objs dir\l$ngx objext#g" \ 


"Ss#^\(.*\.\)cc\\$#Sngx objs dir\l$ngx objext#g" \ 


a 


i 


EN NS$#Sngx objs dir\l$ngx objext#g" \ 
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"Ss#^\(.*\.\)S\\$#$ngx objs dir\l$ngx objext#g". 
ngx Src= echo $ngx src | sed -e "s/\// $ngx regex dirsep/g". 
cat << END >> SNGX MAKEFILE 
Sngx obj: \$ (ADDON DEPS) $ngx contSngx src 
$ngx cc$ngx tabSngx objout$ngx obj$ngx tab$ngx src$NGX AUX 
END 























done 
£1i 





下 面 这 段 代 码 用 于 将 各 个 模块 的 目标 文件 设置 到 ngx_obj 变 量 中 ， 紧 接 大 会 生成 Makefile 
里 的 链接 代码 ， 并 将 所 有 的 目标 文件 、 库 文件 链接 成 二 进 制 程序 。 








for ngx src in SNGX ADDON SRCS 
do 
ngx obj="addon/ basename \ dirname S$ngx src\  " 
test -d $NGX OBJS/$ngx obj || mkdir -p SNGX OBJS/$ngx obj 
ngx obj= echo S$ngx obj/\ basename Sngx SrcN \\ 
| sed -e "s/\// $ngx regex dirsep/g". 
ngx all srcs="$ngx all srcs $ngx obj" 
done.… 








cat << END >> SNGX MAKEFILE 
SNGX OBJS${ngx dirsep}nginx$ {ngx binext}: 
$ngx deps$ngx spacer \$ (LINK) 
${ngx long start}${ngx binout}$NGX OBJS${ngx dirsep}nginx$ngx long cont$ngx 
objssngxlibs$ngx link 
$ngx_rcc 
${ngx long end} 
END 

















综 上 可 知 ， 第 三 方 模块 就 是 这 样 仍 入 到 Nginx 程 序 中 的 。 


3.3.3 ”直接 修改 Makefile 文 件 





3.3.2 市 中 介绍 的 方法 量 无 疑问 是 最 方便 的 ， 因 为 大 量 的 工作 已 由 Nginx 中 的 configure 脚 本 
帮 我 们 做 好 了 。 在 使 用 其 他 第 三 方 模块 时 ， 一 般 也 推荐 使 用 该 方法 。 





我 们 有 时 可 能 需要 更 灵活 的 方式 ， 比 如 重新 决定 ngx module t*ngx modules[] 数 组 中 各 个 
模块 的 顺序 ， 或 者 在 编译 源 代 码 时 需要 加 入 一 些 独特 的 编译 选项 ， 那 么 可 以 在 执行 完 
configure 后 ， 对 生成 的 objsmgx modules.c 和 objs/Makefile 文 件 直 接 进 行 修 改 。 








在 修改 objs/ngx_modules.c 时 ， 首 先 要 添加 新 增 的 第 三 方 模块 的 声明 ， 如 下 所 示 。 





exte 中 |ok hefte[] Ftd http: / /Ww | 1 NuUxorobe. con 








其 次 ， 在 合适 的 地 方 将 模块 加 入 到 ngx_modules 数 组 中 。 





ngx module 七 xngx modules[] = { 





&ngx http upstream ip hash module, 
&ngx http mytest module, 
&ngx http write filter module, 





NULL 





注意 ， 模 块 的 顺序 很 重要 。 如 果 同 时 有 两 个 模块 表示 对 同一 个 请 求 感 兴 趣 ， 那 么 只 有 顺 
序 在 前 的 模块 会 被 调用 。 


修改 objs/Makefile 时 需要 增加 编译 源 代 码 的 部 分 ， 例 如 : 








objs/addon/httpmodule/ngx http mytest module.o: $ (ADDON DEPS) \ 
../sample/httpmodule// ngx nttp mytest module.c 
$ (CC) -ce $ (CFLAGS) $ (ALL INCS) \ 
-oO objs/addon/nttpmodule/ngx nttp mytest module.o \ 
../sample/httpmodule// ngx nttp mytest module.c 








还 需要 把 目标 文件 链接 到 Nginx 中 ， 例 如 : 





objs/nginx: objs/src/core/nginx.o \ 


objs/addon/httpmodule/ngx http mytest module.o \ 
objs/ngx modules.o 

$ (LINK) -o objs/nginx \ 

objs/src/core/nginx.o \ 


objs/addon/httpmodule/ngx http mytest module.o \ 
objs/ngx modules.o \ 
-lpthread -lcrypt -lpcre -lcrypto -lcrypto -1z 





请 慎 用 这 种 直接 修改 Makefile 和 ngx modules.c 的 方法 ， 不 正确 的 修改 可 能 导致 Neginx 工 作 
不 正常 。 
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3.4 HTTP 模块 的 数据 结构 


定义 HTTP 模块 方式 很 简单 ， 例 如 : 





ngx module t ngx http mytest module; 








其 中 ，ngx_module t 是 一 个 Nginx 模 块 的 数据 结构 ( 详 见 8.2 节 〉 。 下 面 来 分 析 一 下 Nginx 
模块 中 所 有 的 成 员 ， 如 下 所 示 : 





typedef struct ngx module s ngx module t; struct ngx module s { 


/* 下 面 的 


ctx index、 


index、 


spare0、 


sparel、 


spare2、 


spare3、 
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version 变 量 不 需要 在 定义 时 赋值 ， 可 以 用 


Nginx 准 备 好 的 宏 


NGX_MODULE V1 来 定义 ， 它 已 经 定义 好 了 这 





7 个 值 。 


#define NGX MODULE V1 0 O07 0 OF OF Oy 





对 于 一 类 模块 (由 下 面 的 


type 成 员 决 定 类 别 ) 而 言 ， 


ctx_index 表 示 当 前 模块 在 这 类 模块 中 的 序号 。 这 个 成 员 常 常 是 由 管理 这 类 模块 的 一 个 


Nginx 核 心 模块 设置 的 ， 对 于 所 有 的 


HTTP 模 块 而 言 ， 


ctx index 是 由 核心 模块 
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ngx_http module 设 置 的 。 


ctx index 非常 重要 ， 





Nginx 的 模块 化 设计 非常 依赖 于 各 个 模块 的 顺序 ， 它 们 既 用 于 表达 优先 级 ， 也 用 于 表明 每 个 模块 的 位 置 ， 借 以 帮助 
Nginx 框 架 快 速 获得 茶 个 模块 的 数据 ( 
HTTP 框 架设 置 
ctx index 的 过 程 参 见 
10 .7 节 ) 
Eh 
ngx uint t ctx index; 


/*index 表 示 当 前 模块 在 


ngx_modules 数 组 中 的 序号 。 注 意 ， 


i htt po: // WW | 1 Nuxpor obe. con 





index 表 示 当 前 模块 在 所 有 模块 中 的 序号 ， 它 同样 关键 。 


Nginx 启 动 时 会 根据 


ngx_modules 数 组 设置 各 模块 的 


index 值 。 例 如 : 


ngx max module = 0; 


for (i = 0; ngx modules[i]; i++) { 


ngx modules[i]->index = ngx max module++; } 


4 


ngx uint 七 index; 


// spare 系 列 的 保留 变量 ， 暂 未 使 用 


ngx uint 七 spare0; 
ngx uint t sparel; 
ngx uint t spare2; 
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// 模块 的 版 本 ， 便 于 将 来 的 扩展 。 目 前 只 有 一 种 ， 默 认为 


ngx uint 七 version; 


/*ctx 用 于 指向 一 类 模块 的 上 下 文 结构 体 ， 为 什么 需要 


ctx 呢 ?因为 前 面 说 过 ， 


Nginx 模 块 有 许多 种 类 ， 不 同类 模块 之 间 的 功能 差别 很 大 。 例 如 ， 事 件 类 型 的 模块 主要 处 理 


I/O 事 件 相 关 的 功能 ， 


HTTP 类 型 的 模块 主要 处 理 


HTTP 应 用 层 的 功能 。 这 样 ， 每 个 模块 都 有 了 自己 的 特性 ， 而 


ctx 将 会 指向 特定 类 型 模块 的 公共 接口 。 例 如 ， 在 


HTTP 模 块 中 ， 


Ctx 需 要 指向 
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ngx_http module 七 结构 体 


*/ 


void ele 


// commands 将 处 理 


nginx.conf 中 的 配置 项 ， 详 见 第 


ngx command t *commands; 


/*type 表 示 该 模块 的 类 型 ， 它 与 


Ctx 指针 是 紧密 相关 的 。 在 官方 


Nginx 中 ， 它 的 取 值 范围 是 以 下 


5 种 : 


NGX HTTP _ MODULE 





要 
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NGX CORE MODULE、 











NGX CONF _ MODULE 





本 

















NGX_EVENT MODUIE、 


NGX_ MAIL MODULE 


加 
令 





5 种 模块 间 的 关系 参考 图 


8-2。 实 际 上 ， 还 可 以 自 定义 新 的 模块 类 型 


2 


ngx uint 七 type; 


/* 在 


Nginx 的 启动 、 停 止 过 程 中 ， 以 下 


7 个 函数 指针 表示 有 
7 个 执行 点 会 分 别 调用 这 
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7 种 方法 ( 参 


BS 
号 


8.6 节 ) 。 对 于 任 一 个 方法 而 言 ， 如 果 不 需 要 


Nginx 在 某 个 时 刻 执 行 它 ， 那 么 简单 地 把 它 设 为 


NUILIL 空 指针 即 可 


二 


/* 虽 然 从 字面 上 理解 应 当 在 


master 进 程 启动 时 回调 


init master， 但 到 目前 为 止 ,框架 代码 从 来 不 会 调用 它 ， 因 此 ， 可 将 





init master 设 为 


NULL */ 


ngx int t (*init master) (ngx log t *10g); /*init module 回 调 方法 在 初始 化 所 有 模块 时 被 调用 。 在 
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master/worker 模 式 下 ， 这 个 阶段 将 在 启动 


gi 


worker 子 进程 前 完 


*/ 
ngx int t (*init module) (ngx cycle tt *cycle); /* init process 回 调 方法 在 正常 服务 前 被 调用 。 在 
master/worker 模 式 下 ， 多 个 
worker 子 进程 已 经 产生 ， 在 每 个 
worker 进 程 的 初始 化 过 程 会 调用 所 有 模块 的 
init process 咏 数 
*/ 
ngx int t (*init process) (ngx cycle 七 *cycle); /* 由 于 


Nginx 和 暂 不 支持 多 线程 模式 ， 所 以 


init _thread 在 框架 代码 中 没有 被 调用 过 ， 设 为 
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ngx int 七 (*init thread) (ngx cycle t *cycle); // 同上 ， 


exit thread 也 不 支持 ， 设 为 


NULL 


void (*exit thread) (ngx cycle t *cycle); /* exit process 回 调 方法 在 服务 停止 前 调用 。 在 


master/worker 模 式 下 ， 


worker 进 程 会 在 退出 前 调用 它 


Rf 
void (*exit process) (ngx cycle t *cycle); // exit master 回 调 方法 将 在 
master 进 程 退 出 前 被 调用 
void (*exit master) (ngx cycle t *cycle); /* 以 下 


spare_ hook 变量 也 是 保留 字段 ， 目 前 没有 使 用 ， 但 可 用 


口 由 掉 岂 有 有 和 所 掉 由 http' /wNv inuxorobe. con 





Nginx 提 供 的 


NGX_MODULE V1 _PADDING 宏 来 填充 。 看 一 下 该 宏 的 定义 : 





#define NGX MODULE V1 PADDING 0, 0, 0, 0, 0, 0, 0, 0*/ 





uintptr t 


uintptr t 


Uintptr t 


UintpttE 十 


uintptr t 


uintptr t 


uintptr t 


uintptr t 


spare hook0; 


spare hookl; 


spare hook2; 


spare hook3; 





spare hook4; 





spare hook5; 


spare hooke6; 


spare hook7; 





定义 一 个 HTTP 模 块 时 ， 





务必 把 type 字 段 设 为 NGX _ HTTP MODULE。 





对 于 下 列 回调 方法 : init module、init process、exit process、exit master， 调 用 它们 的 是 Nginx 的 框架 代码 。 换 句 话 说 





| 四 


定义 HTTP 模块 时 ， 最 











EE 要 的 是 要 设置 ctx 和 commands 这 两 个 成 员 。 对 于 HTTP 类 型 的 模块 来 说 ，ngx_module t 中 的 ct 





HTTP 框 架 在 读 取 、 重 载 配置 文件 时 定义 了 由 ngx_http _ module t 接 口 描述 的 8 个 阶段 ，HTTP 框 架 在 启动 过 程 中 会 在 每 


[HTDD 
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typedef struct { 


// 解析 配置 文件 前 调用 


ngx int 七 (*preconfiguration) (ngx conf t *cf); // 完成 配置 文件 的 解 析 后 调 用 


ngx int 七 (*postconfiguration) (ngx conf 七 *cf); /* 当 需要 创 建 数据 结构 用 于 存储 


main 级 别 ( 直属 各 


http{...} 块 的 配置 项 ) 的 全 局 配置 项 时 ， 可 以 通过 


create main conf 回 调 方 法 创 建 存储 全 局 配置 项 的 结构 体 


*/ 


void *(*create main conf) (ngx conf t *cf); // 常用 于 初始 化 





main 级 别 配 置 项 


char * (tinit main conf) (ngx Conf t ef, void conf); /* 当 需要 创 建 数据 结构 用 于 存储 
srv 级 别 (直属 于 虚拟 主机 
server{...} 块 的 配置 项 ) 的 配置 项 时 ， 可 以 通过 实现 


create_srv_conf 回 调 方 法 创 建 存储 
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srv 级 别 配置 项 的 结构 体 


*/ 

void *(*create srv conf) (ngx conf t *cf); // merge srv_conf 回 调 方 法 主要 用 于 合并 
main 级 别 和 
srv 级 别 下 的 同名 配置 项 

char * (xmerge_srv_conf) (ngx conf t cf void prev， void *conf); /* 当 需要 创建 数据 结构 用 于 存储 
loc 级 别 (直属 于 
location{...} 块 的 配置 项 ) 的 配置 项 时 ， 可 以 实现 
create loc conf 回 调 方法 

*/ 

void *(*create loc conf) (ngx conf t *cf); // merge loc conf 回 调 方 法 主要 用 于 合并 
srv 级 别 和 
loc 级 别 下 的 同名 配置 项 

char * (x*merge loc conf) (ngx conf t cf, void prev, void *conf); } ngx http module t; 


不 过 ， 这 8 个 阶段 的 调用 顺序 与 上 述 定义 的 顺序 是 不 同 的 。 在 Nginx 启 动 过 程 中 ，HTTP 框 染 调 月 














日 这些 回 调 方法 的 实 开 
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1) create main conf 


2) create_STV_conf 


3) create loc conf 


4) preconfiguration 


$5) init main conf 


6) merge srv_conf 


7) merge loc conf 


8) postconfiguration 





commands 数 组 用 于 定义 模块 的 配置 文件 参数 ， 每 一 个 数组 元 素 都 是 ngx_command t 类 型 ， 数 组 的 结尾 用 ngx_null_con 





typedef struct ngx command s ngx_command t; struct ngx command s { 


// 配置 项 名 称 ， 如 


"gzip" 
ngx_ str 七 name; 


/* 配 置 项 类 型 ， 


type 将 指定 配置 项 可 以 出 现 的 位 置 。 例 如 ， 出 现在 
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server{} 或 


location{} 中 以 及 它 可 以 携 带 的 参数 个 数 


站 


ngx uint 七 type; 


7X 


name 中 指定 的 配置 项 后 ， 将 会 调用 


set 方 法 处 理 配 置 项 的 参数 


char *(*set) (ngx conf 七 cf, ngx command 上 cmd, void *conf); // 在 配置 文件 中 的 偏 移 量 





ngx uint t conf;} 


/* 通 常用 于 使 用 预 设 的 解析 方法 解析 配置 项 ， 这 是 配置 模块 的 一 个 优秀 设计 。 它 需要 与 
conf 配 合 使 用 ， 在 第 


i 
4 章 中 详细 介绍 
A 
ngx uint t offset; 


// 配置 项 读 取 后 的 处 理 方法 ， 必 须 是 


ngx_ conf Post 七 结 构 的 指针 


void *post; 
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ngx_null command 只 是 一 个 空 的 ngx_command t， 如 下 所 示 : 








#define ngx null command { ngx null string, 0, NULL, 0, 0, NULL } 
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3.$ 定义 自己 的 HITP 模 块 


上 文中 我 们 了 解 了 定义 HTTP 模 块 时 需要 定义 哪些 成 员 以 及 实现 哪些 方法 ， 但 在 定义 
HTTP 模 块 前 ， 首 先 需 要 确定 自 定义 的 模块 应 当 在 什么 样 的 场景 下 开始 处 理 用 户 请 求 ， 也 就 
是 说 ， 先 要 弄 清楚 我 们 的 模块 是 如 何 介 入 到 Nginx 处 理 用 户 请 求 的 流程 中 的 。 从 2.4 节 中 的 
HTTP 配 置 项 意义 可 知 ， 一 个 HITP 请 求 会 被 许多 个 配置 项 控制 ， 实 际 上 这 是 因为 一 个 HITP 
请 求 可 以 被 许多 个 HTTP 模 块 同时 处 理 。 这 样 一 来 ， 肯 定 会 有 一 个 先后 问题 ， 也 就 是 说 ， 谁 
先 处 理 请 求 谁 的 “权力 ”就 更 大 。 例 如 ，ngx_http access_module 模 块 的 deny 选 项 一 旦 得 到 满足 
后 ，Nginx 就 会 决定 拒绝 来 自 菜 个 Pp 的 请 求 ， 后 面 的 诸如 root 这 种 访问 静态 文件 的 处 理 方式 是 
得 不 到 执行 的 。 另 外 ， 由 于 同一 个 配置 项 可 以 从 属于 许多 个 server、location 配 置 块 ， 那 么 这 
个 配置 项 将 会 针对 不 同 的 请 求 起 作用 。 因 此 ， 现 在 面临 的 问题 是 ， 我 们 希望 自己 的 模块 在 哪 
个 时 刻 开 始 处 理 请 求 ? 是 希望 自己 的 模块 对 到 达 Nginx 的 所 有 请 求 都 起 作用 ， 还 是 希望 只 对 
某 一 类 请 求 ( 如 URI 匹 配 了 location 后 表达 式 的 请 求 )》 起 作用 ? 

















Nginx 的 HTTP 框 架 定义 了 非常 多 的 用 法 ， 我 们 有 很 大 的 自由 来 定义 自己 的 模块 如 何 介 入 
HTTP 请 求 的 处 理 ， 但 本 章 只 想 说 明 最 简单 、 最 常见 的 HTTP 模 块 应 当 如 何 编写 ， 因 此 ， 我 们 
这 样 定义 第 一 个 HTTP 模 块 介 入 Nginx 的 方式 : 


1) 不 希望 模块 对 所 有 的 HTTP 请 求 起 作用 。 


2) 在 nginx.conf 文 件 中 的 http{}、server{} 或 者 location 们 块 内 定义 mytest 配 置 项 ， 如 果 一 
个 用 户 请 求 通 过 主机 域名 、URI 等 区 配 上 了 相应 的 配置 块 ， 而 这 个 配置 块 下 义 具 有 mytest 配 置 
项 ， 那 么 希望 mytest 模 块 开 始 处 理 请 求 。 








在 这 种 介入 方式 下 ， 模 块 处 理 请 求 的 顺序 是 固定 的 ， 即 必须 在 HTTP 框 架 定义 的 
NGX_HTTP_CONTENT_PHASE 阶 段 开 始 处 理 请 求 ， 具 体内 容 下 文 详 述 。 
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下 面 开 始 按照 这 种 方式 定义 mytest 模 块 。 首 先 ， 定 义 mytest 配 置 项 的 处 理 。 从 上 文中 关于 
ngx_command t 结 构 的 说 明 来 看 ， 只 需要 定义 一 个 ngx_command tt 数组 ， 并 设置 在 出 现 mytest 
配置 后 的 解析 方法 由 ngx_http_mytest 担 当 ”， 如 下 所 示 : 





static ngx command t ngx http mytest commands[] = { 





{ ngx string("mytest"), 


NGX HTTP MAIN CONF|NGX HTTP SRV CONF|NGX HTTP LOC CONF|NGX HTTP LMT CONF|NGX CONF NOARGS, ngx http mytest 


NGX HTTP LOC CONF OFFSET, 








NULL }, 


ngx null command 





其 中 ，ngx_http_mytest 是 ngx command tt 结构 体 中 的 set 成 员 ( 完 整定 义 为 char*(*set) 
(ngx_conf t*cfngx command t*cmd,void*conf);) ， 当 在 某 个 配置 块 中 出 现 mytest 配 置 项 时 ， 
Nginx 将 会 调用 ngx_http_mytest 方 法 。 下 面 看 一 下 如 何 实现 ngx_http_mytest 方 法 。 





static char 大 


ngx http mytest (ngx conf t *cf, ngx command t cmd, void conf) { 


ngx http core loec conf 七 *clef; 





/* 首 先 找到 


mytest 配 置 项 所 属 的 配置 块 ， 
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clcf 看 上 去 像 是 


location 块 内 的 数据 结构 ， 其 实 不 然 ， 它 可 以 是 


main、 


srVv 或 者 


loc 级 别 配 置 项 ， 也 就 是 说 ， 在 每 个 


http{} 和 


server{]} 内 也 都 有 一 个 


ngx http core loc conf 结构 体 





Sy 


clcf = ngx http conf get module loc conf(cf, ngx http core module); /*HTTP 框 架 在 处 理 用 户 请 求 进行 到 











NGX_HTTP_CONTENT PHASE 阶 段 时 ， 如 果 请 求 的 主机 域名 、 
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URI 与 


mytest 配 置 项 所 在 的 配置 块 相 匹 配 ， 就 将 调用 我 们 实现 的 


ngx http mytest handler 方 法 处 理 这 个 请 求 


*/ 


clcf->handler = ngx http mytest handler; return NGX CONF OK; 





当 Nginx 接 收 完 HITP 请 求 的 头 部 信息 时 ， 就 会 调用 HTTP 框架 处 理 请 求 ， 另 外 在 11.6 节 描 
述 的 NGX_HTTP_CONTENT _ PHASE 阶段 将 有 可 能 调用 mytest 模 块 处 理 请 求 。 在 
ngX_http_mytest 方 法 中 ， 我 们 定义 了 请 求 的 处 理 方 法 为 ngx http mytest handler， 举 个 例子 来 
说 ， 如 果 用 户 的 请 求 URI 是 /test/example， 而 在 配置 文件 中 有 这 样 的 location 块 : 








Location /test { 


mytest; 





那么 ，HTTP 框 架 在 NGX HTTP_ CONTENT PHASE 阶 段 就 会 调用 到 我 们 实现 的 
ngx_http_mytest_handler 方 法 来 处 理 这 个 用 户 请 求 。 事 实 上 ，HTTP 框 染 共 定义 了 11 个 阶段 (第 
三 方 HTTP 模 块 只 能 介入 其 中 的 7 个 阶段 处 理 请 求 ， 详 见 10.6 节 )〉 ， 本 章 只 关注 
NGX_HTTP_CONTENT_PHASE 处 理 阶段 ， 多 数 HTTP 模 块 都 在 此 阶段 实现 相关 功能 。 下 面 简 
单 说 明 一 下 这 11 个 阶段 。 
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typedef enum { 


// 在 接收 到 完整 的 


HTTP 头 部 后 处 理 的 


HTTP 阶 段 


NGX HTTP POST READ PHASE = 0， 











/* 在 还 没有 查询 到 


URI 匹 配 的 


location 前 ， 这 时 





人 


rewrite 重 


URL 也 作为 一 个 独立 的 


HTTP 阶 段 
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/* 根 据 


URI 寻 找 匹 配 的 


location， 这 个 阶段 通常 由 


ngx_http_core module 模 块 实现 ， 不 建议 其 他 


HTTP 模 块 重新 定义 这 一 阶段 的 行为 


wy 


NGX HTTP FIND CONFIG PHASE 





~ 





NGX HTTP FIND CONFIG PHASE 阶 段 之 后 重 写 








URL 的 意义 与 





NGX _ HTTP SERVER REWRITE PHASE 阶 段 显然 是 不 同 的 ， 因 为 这 两 者 会 导致 查找 到 不 同 的 




















location 块 ( 
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location 是 与 


URI 进 行 匹配 的 ) 


*y 





NGX HTTP REWRITE PHASE, 














/* 这 一 阶段 是 用 于 在 





加 


rewrite 重 


URL 后 重新 跳 到 





NGX HTTP FIND CONFIG PHASE 阶 段 ， 找 到 与 新 的 








URI 匹 配 的 


location。 所 以 ， 这 一 阶段 是 无 法 由 第 三 方 


HTTP 模 块 处 理 的 ， 而 仅 由 


ngx_http core module 模 块 使 用 
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NGX HTTP POST REWRITE PHASE, 


// 处 理 








NGX_HTTP_ACCESS_PHASE 阶 段 前 ， 


HTTP 模 块 可 以 介入 的 处 理 阶段 





NGX HTTP PREACCESS PHASE 














~ 


/* 这 个 阶段 用 于 让 


HTTP 模 块 判断 是 否 允 许 这 个 请 求 访问 


Nginx 服 务 器 








NGX HTTP ACCESS PHASE, 


/* 当 


NGX_HTTP ACCESS PHASE 阶段 中 








HTTP 模 块 的 
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handler 处 理 方 法 返回 不 允许 访问 的 错误 码 时 (实际 是 





NGX_HTTP FORBIDDEN 或 者 


NGX_HTTP_UNAUTHORIZED) ， 这 个 阶段 将 负责 构造 拒绝 服务 的 用 户 响应 。 所 以 ， 这 个 阶段 实际 上 用 于 给 


NGX_HTTP_ACCESS_PHASE 阶 段 收尾 





4 


NGX HTTP POST ACCESS PHASE 





~ 





try_files 配 置 项 而 设立 的 。 当 


HTTP 请 求 访问 静态 文件 资源 时 ， 


try_files 配 置 项 可 以 使 这 个 请 求 顺序 地 访问 多 个 静态 文件 资源 ， 如 果 某 一 次 访问 失败 ， 则 继续 访问 


try_files 中 指定 的 下 一 个 静态 资源 。 另 外 ， 这 个 功能 完全 是 在 


NGX HTTP TRY FILES PHASE 阶 段 中 实现 的 
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NGX HTTP TRY FILES PHASE, 











// 用 于 处 理 


HTTP 请 求 内 容 的 阶段 ， 这 是 大 部 分 


HTTP 模 块 最 喜欢 介入 的 阶段 





NGX HTTP CONTENT PHASE 





~ 





/* 处 理 完 请 求 后 记录 日 志 的 阶段 。 例 如 ， 


ngx http log module 模 块 就 在 这 个 阶段 中 加 入 了 一 个 


handler 处 理 方 法 ， 使 得 每 个 


HTTP 请 求 处 理 完毕 后 会 记录 


access 1og 日 志 


G4 


NGX HTTP LOG PHASE 
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当然 ， 用 户 可 以 在 以 上 11 个 阶段 中 任意 选择 一 个 阶段 让 mytest 模 块 介入 ， 但 这 需要 学 习 
完 第 10 章 、 第 11 章 的 内 容 ， 完 全 熟悉 了 HTTP 框 架 的 处 理 流程 后 才 可 以 做 到 。 





暂且 不 管 如 何 实现 处 理 请 求 的 ngx_http_mytest_handler 方 法 ， 如 果 没 有 什么 工作 是 必须 在 
HTTP 框 架 初 始 化 时 完成 的 ， 那 就 不 必 实 现 ngx_http_ module t 的 8 个 回调 方法 ， 可 以 像 下 面 这 
样 定义 ngx http module 接口 。 





static ngx http module t ngx http mytest module ctx = { 





NULL, /* preconfiguration */ 

NULL, /* postconfiguration */ 

NULL, /* create main configuration */ 
NULL, /* init main configuration */ 

NULL, /* create server configuration */ 
NULL, /* merge server configuration */ 
NULL, /* create location configuration */ 


NULL /* merge location configuration */ 





最 后 ， 定 义 mytest 模 块 : 





ngx module t ngx http mytest module = { 





NGX MODULE V1, 
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&ngx http mytest module ctx, 





ngx_ http mytest commands, 





NGX HTTP MODULE, 


NULL, 


NULL, 











NULL, 





NULL, 


NULL, 


NULL, 


NULL, 


NGX MODULE V1 PADDING 





/* module context */ 


/* module directives */ 





/* module type */ 


init master */ 


init module */ 


init process */ 


init thread */ 


exit thread */ 


exit process */ 


exit master */ 





这 样 ，mytest 模 块 在 编译 时 将 会 被 加 入 到 ngx modules 全 局 数组 中 。Nginx 在 启动 时 ， 会 调 
用 所 有 模块 的 初始 化 回调 方法 ， 当 然 ， 这 个 例子 中 我 们 没有 实现 它们 (也 没有 实现 HTTP 框 
架 初始 化 时 会 调用 的 ngx http module t 中 的 8 个 方法 ) 。 
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3.6 ”处 理 用户 请 求 


本 节 介 绍 如 何 处 理 一 个 实际 的 HTTP 请 求 。 回 顾 一 下 上 文 ， 在 出 现 mytest 配 置 项 时 ， 
ngx http mytest 方 法 会 被 调用 ， 这 时 将 ngx_http_core loc_conf t 结 构 的 handler 成 员 指 定 为 
ngx_http_mytest_handler， 另 外 ，HTTP 框 架 在 接收 完 HITP 请 求 的 头 部 后 ， 会 调用 handler 指 辐 
的 方法 。 下 面 看 一 下 handler 成 员 的 原型 ngx_http_handler_pt: 





typedef ngx int 七 (*ngx http handler pt) (ngx http request t *r); 





从 上 面 这 段 代码 可 以 看 出 ， 实 际 处 理 请 求 的 方法 negx_http_mytest handler 将 接收 一 个 
ngx_http_request {类 型 的 参数 r， 返 回 一 个 ngx_int_t (参见 3.2.1 节 ) 类 型 的 结果 。 下 面 先 探讨 
一 下 ngx http mytest handler 方 法 可 以 返回 什么 ， 再 看 一 下 参数 r 包 含 了 哪些 Nginx 已 经 解析 完 
的 用 户 请 求 信息 。 


3.6.1 ”处 理 方法 的 返回 值 


这 个 返回 值 可 以 是 HTTP 中 响应 包 的 返回 码 ， 其 中 包括 了 HTTP 框 架 已 经 
在 /src/http/ngx_http_request.h 文 件 中 定义 好 的 宏 ， 如 下 所 示 。 

































































#define NGX HTTP OK 200 
#define NGX HTTP CREATED 201 
#define NGX HTTP ACCEPTED 202 
define NGX HTTP NO CONTENT 204 
define NGX HTTP PARTIAL CONTENT 206 
define NGX HTTP SPECIAL RESPONSE 300 
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#define NGX HTTP MOVED PERMANENTLY 301 





























define NGX HTTP MOVED TEMPORARILY 302 


















































































































































define NGX HTTP SEE OTHER 303 
define NGX HTTP NOT MODIFIED 304 
#define NGX HTTP TEMPORARY REDIRECT 307 
#define NGX HTTP BAD REQUEST 400 
#define NGX HTTP UNAUTHORIZED 401 
#define NGX HTTP FORBIDDEN 403 
#define NGX HTTP NOT FOUND 404 
define NGX HTTP NOT ALLOWED 405 
define NGX HTTP REQUEST TIME OUT 408 
define NGX HTTP CONFLICT 409 
#define NGX HTTP LENGTH REQUIRED 411 
#define NGX HTTP PRECONDITION FAILED 412 





















































#define NGX HTTP REQUEST ENTITY TOO LARGE 413 
#define NGX HTTP REQUEST URI TOO LARGE 414 
#define NGX HTTP UNSUPPORTED MEDIA TYPE 415 
#define NGX HTTP RANGE NOT SATISFIABLE 416 














/* The special code to close connection without any response */ 


#define NGX HTTP CLOSI 
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[mal 


444 








define NGX HTTP NGINX CODES 494 








define NGX HTTP REQUEST HEADER TOO LARGE 494 


















































































































































define NGX HTTPS CERT ERROR 495 
define NGX HTTPS NO CERT 496 
#define NGX HTTP TO HTTPS 497 
#define NGX HTTP CLIENT CLOSED REQUEST 499 
#define NGX HTTP INTERNAL SERVER ERROR 500 
#define NGX HTTP NOT IMPLEMENTED 501 
define NGX HTTP BAD GATEWAY 502 
define NGX HTTP SERVICE UNAVAILABLE 503 
define NGX HTTP GATEWAY TIME OUT 504 
define NGX HTTP INSUFFICIENT STORAGE 507 

















@ 注意 ”以 上 返回 值 除 了 RFC2616 规 范 中 定义 的 返回 码 外 ， 还 有 Nginx 自 身 定义 的 
HTTP 返 回 码 。 例 如 ，NGX_HTTP_CLOSE 就 是 用 于 要 求 HTTP 框 架 直 接 关 闭 用 户 连接 的 。 


在 ngx_http_mytest_handler 的 返回 值 中 ， 如 果 是 正常 的 HTTP 返 回 码 ，Nginx 就 会 按照 规范 
构造 合法 的 响应 包 发 送 给 用 户 。 例 如 ， 假 设 对 于 PUT 方 法 暂 不 支持 ， 那 么 ， 在 处 理 方 法 中 发 
现 方 法 名 是 PUT 时 ， 返 回 NGX HTTP_NOT ALLOWED， 这 样 Nginx 也 就 会 构造 类 似 下 面 的 响 
应 包 给 用 户 。 





http/1.1 405 Not Allowed Server: nginx/1.0.14 


Date: Sat, 28 Apr 2012 06:07:17 GMT 
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Content-Type: text/html 


Content-Length: 173 


Connection: keepalive 


<html> 


<head><title>405 Not Allowed</title></head> <body bgcolor="white"> 


<Center><h1>405 Not Allowed</h1l></center> <hr><center>nginx/1.0.14</center> </body> 


</nhntml> 





在 处 理 方法 中 除了 返回 HTTP 啊 应 人 码 外 ， 还 可 以 返回 Nginx 全 局 定义 的 儿 个 错误 码 ， 包 
括 : 














#define NGX OK 0 
#define NGX ERROR -1 
define NGX AGAIN -2 
define NGX BUSY =3 
define NGX DONE -4 
define NGX DECLINED =65 




















#define NGX ABORT -6 





这 些 错 误 码 对 于 Nginx 自 身 提供 的 大 部 分 方法 来 说 都 是 通用 的 。 所 以 ， 当 我 们 最 后 调用 
ngx_http_output filter( 参 见 3.7 闻 )〉 癌 用 户 发 送 啊 应 包 时 ， 可 以 将 ngx_http_output_filter 的 返回 
值 作为 ngx_http_mytest_ handler 方 法 的 返回 值 使 用 。 例 如 : 








static ngx int t ngx http mytest handler (ngx http request t *r) { 








ngx int t rc = ngx http send header(r); if (rc == NGX ERROR || rc > NGX OK || r->header only) { 


return rc; 


return ngx http output filter(r, &out); } 








当然 ， 直 接 返 回 以 上 7 个 通用 值 也 是 可 以 的 。 在 不 同 的 场景 下 ， 这 7 个 通用 返回 值 代表 的 
含义 不 尽 相 同 。 在 mytest 的 例子 中 ，HITP 框 架 在 NGX_HTTP_CONTENT_ PHASE 阶段 调用 
ngx http mytest handler 后 ， 会 将 ngx http mytest handler 的 返回 值 作为 参数 传 给 
ngx http finalize request 方 法 ， 如 下 所 示 。 





if (r->content handler) { 


r->write event handler = ngx http request empty handler; ngx http finalize request(r, r->content handle 





上 面 的 r->content handler 会 指向 ngx http mytest handler 处 理 方 法 。 也 就 是 说 ， 事 实 上 
ngx http finalize _ request 决定 了 nex http mytest handler 如 何 起 作用 。 本 章 不 探讨 
ngx_http finalize_ request 的 实现 《〈 详 见 11.10 节 ) ， 只 简单 地 说 明 一 下 4 个 通用 返回 码 ， 另 外 ， 
在 11.10 节 中 介绍 这 4 个 返回 码 引 发 的 Nginx 一 系列 动作 。 


` NGX_OK: 表示 成 功 。Nginx 将 会 执行 该 请 求 的 后 续 动作 (如 执行 Subrequest 或 撤 
销 这 个 请 求 ) 。 


DECLINED: 继续 在 NGX_HTIP_CONTENT_PHASE 阶 段 寻 找 下 一 个 对 于 该 请 
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求 感 兴趣 的 HTTP 模 块 来 再 次 处 理 这 个 请 求 。 


- NGX_DONE: 表示 到 此 为 止 ， 同 时 HTTP 框 架 将 暂时 不 再 继续 执行 这 个 请 求 的 后 续 部 
分 。 事 实 上 ， 这 时 会 检查 连接 的 类 型 ， 如 果 是 keepalive 类 型 的 用 户 请 求 ， 就 会 保持 住 HTTP 连 
接 ， 然 后 把 控制 权 交 给 Nginx。 这 个 返回 码 很 有 有 用， 考虑 以 下 场景 在 一 个 请 求 中 我 们 必须 
访问 一 个 耗 时 极 长 的 操作 (比如 某 个 网 络 调用 ) ， 这 样 会 阻塞 住 Nginxg， 又 因为 我 们 没有 把 
控制 权 交 还 给 Npginx， 而 是 在 negx_http_mytest_handler 中 让 Neginx worker 进 程 休眠 了 (如 等 待 网 
络 的 回 包 ) ， 所 以 ， 这 就 会 导致 Nginx 出 现 性 能 问题 ， 该 进程 上 的 其 他 用 户 请 求 也 得 不 到 响 
应 。 可 如 果 我 们 把 这 个 耗 时 极 长 的 操作 分 为 上 下 两 个 部 分 (就 像 Linux 内 核 中 对 中 断 处 理 的 
划分 ) ， 上 半 部 分 和 下 半 部 分 都 是 无 阻塞 的 〈 耗 时 很 少 的 操作 ) ， 这 样 ， 在 
ngx_http_mytest_handlet 进 入 时 调用 上 半 部 分 ， 然 后 返回 NGX_DONE， 把 控制 交还 给 Nginx， 
从 而 让 Nginx 继 续 处 理 其 他 请 求 。 在 下 半 部 分 被 触发 时 (这 里 不 探讨 具体 的 实现 方式 ， 事 实 
上 使 用 upstream 方 式 做 反 向 代理 时 用 的 就 是 这 种 思想 ) ， 再 回调 下 半 部 分 处 理 方 法 ， 这 样 就 
可 以 保证 Nginx 的 高 性 能 特性 了 。 如 果 需 要 彻底 了 解 NGX_DONE 的 意义 ， 那 么 必须 学 习 第 11 
章 内 容 ， 其 中 还 涉及 请 求 的 引用 计数 内 容 。 


` NGX_ERROR: 表示 错误 。 这 时 会 调用 ngx_http_terminate_request 终 止 请 求 。 如 果 还 有 


POST 子 请 求 ， 那 么 将 会 在 执行 完 POST 请 求 后 再 终止 本 次 请 求 。 


3.6.2 ”获取 URI 和 人 参数 


请 求 的 所 有 信息 《如 方法 、URI、 协 议 版 本 号 和 头 部 等 ) 都 可 以 在 传 入 的 
ngx_http request t 类 型 参数 r 中 取得 。ngx_http request t 结 构 体 的 内 容 很 多 ， 本 节 不 会 探讨 
ngx_http request t 中 所 有 成 员 的 意义 ngx_http_request t 结 构 体 中 的 许多 成 员 只 有 HTTP 框 架 
才 感 兴趣 ， 在 11.3.1 节 会 更 详细 的 说 明 ) ， 只 介绍 一 下 获取 URI 和 参数 的 方法 ， 这 非常 简单 ， 
因为 Nginx 提 供 了 多 种 方法 得 到 这 些 信息 。 下 面 先 介 绍 相关 成 员 的 定义 。 
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ngx uint 七 method; ngx uint t http version; ngx str t 





在 对 一 个 用 户 请 求 行进 行 解析 时 ， 可 以 得 到 下 列 4 类 信息 。 
(1》 方法 名 


method 的 类 型 是 ngx_uint t (无 符号 整 型 )， 它 是 Nginx 忽 略 大 小 写 等 情形 时 解析 完 用 户 
请 求 后 得 到 的 方法 类 型 ， 其 取 值 范围 如 下 所 示 。 















































#define NGX HTTP UNKNOWN Ox0001 
#define NGX HTTP GET 0x0002 
#define NGX HTTP HEAD 0x0004 
#define NGxX HTTP POST 0x0008 
#define NGX HTTP PUT 0x0010 
define NGX HTTP DELETE 0x0020 
define NGX HTTP MKCOL 0x0040 
define NGX HTTP COPY 0x0080 
define NGX HTTP MOVE 0x0100 
#define NGX HTTP OPTIONS 0x0200 
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#define NGX HTTP PROPPATCH 0x0800 


#define NGX HTTP LOCK 0x1000 
#define NGX HTTP UNLOCK 0x2000 
#define NGX HTTP TRACE 0x4000 








当 需 要 了 解 用 户 请 求 中 的 HTTP 方 法 时 ， 应 该 使 用 r->method 这 个 整 型 成 员 与 以 上 15 个 宏 
进行 比较 ， 这 样 速度 是 最 快 的 (如 果 使 用 method_name 成 员 与 字符 串 做 比较 ， 那 么 效率 会 差 
很 多 ) ， 大 部 分 情况 下 推荐 使 用 这 种 方式 。 除 此 之 外 ， 还 可 以 用 method_name 取 得 用 户 请 求 
中 的 方法 名 字符 串 ， 或 者 联合 request_start 与 method _ end 指针 取得 方法 名 。method name 是 
ngx_str t 类 型 ， 按 照 3.2.2 节 中 介绍 的 方法 使 用 即 可 。 





request_start 与 method_end 的 用 法 也 很 简单 ， 其 中 request_start 指 向 用 户 请 求 的 首 地 址 ， 同 
时 也 是 方法 名 的 地 址 ，method_end 指 向 方法 名 的 最 后 一 个 字符 〈 注 意 ， 这 点 与 其 他 xxx_end 指 
针 不 同 ) 。 获 取 方 法 名 时 可 以 从 request_start 开 始 向 后 遍历 ， 直 到 地 址 与 method_end 相 同 为 
止 ， 这 段 内 存 存储 着 方法 名 。 











@@ 注音 Nginx 中 对 内 存 的 控制 相当 严格 ， 为 了 避免 不 必要 的 内 存 开销 ， 许 多 需要 用 到 
的 成 员 都 不 是 重新 分 配 内 存 后 存储 的 ， 而 是 直接 指向 用 户 请 求 中 的 相应 地 址 。 例 如 ， 
method_name.data、frequest_statt 这 两 个 指针 实际 指向 的 都 是 同一 个 地 址 。 而 且 ， 因 为 它们 是 
简单 的 内 存 指 针 ， 不 是 指向 字符 串 的 指针 ， 所 以 ， 在 大 部 分 情况 下 ， 都 不 能 将 这 些 u_char* 指 
针 当 做 字符 串 使 用 。 


(2) URI 





ngx_str {类 型 的 uri 成 员 指 向 用 户 请 求 中 的 URI。 同 理 ，u char* 类 型 的 uri_ start 和 uri end 也 
与 request_start、method_end 的 用 法 相似 ， 唯 一 不 同 的 是 ，method_end 指 问 方 法 名 的 最 后 一 个 
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字符 ， 而 uri_ end 指向 URI 结 束 后 的 下 一 个 地 址 ， 也 就 是 最 后 一 个 字符 的 下 一 个 字符 地 址 
(HTTP 框 架 的 行为 )， 这 是 大 部 分 u_char* 类 型 指针 对 “xxx_start* 和 “xxx_end” 变 量 的 用 法 。 








ngx_str_t 类 型 的 exten 成 员 指 同 用 户 请 求 的 文件 扩展 名 。 例 如 ， 在 访问 “GET/a.txt 
HTTP/1.1”* 时 ，exten 的 值 是 {len=3,data="txt"}， 而 在 访问 “GET/a HTTP/1.1” 时 ，exten 的 值 为 


空 ， 也 就 是 flen=0,data=0x0} 。 
uri ext 指 针 指 癌 的 地 址 与 exten.data 相 同 。 


unparsed_uri 表 示 没 有 进行 URL 解 码 的 原始 请 求 。 例 如 ， 当 uri 为 “qb”* 时 ，unparseqd_ uri 
是 “a%20b”( 空格 字符 做 完 编码 后 是 %20)。 


(3) URL 参 数 
args 指 向 用 户 请 求 中 的 URL 参 数 。 
args_start 指 向 URIL 参 数 的 起 始 地 址 ， 配 合 uri_ end 使 用 也 可 以 获得 URL 人 参数 。 


(4) 协议 版 本 





http_protocol 的 data 成 员 指 问 用 户 请 求 中 HTTP 协 议 版 本 字符 串 的 起 始 地 址 ，len 成 员 为 协 
议 版 本 字符 串 长 上 度 。 


http_version 是 Nginx 解 析 过 的 协议 厂 本 ， 它 的 取 值 范围 如 下 : 




















#define NGX HTTP VERSION 9 9 
#define NGX HTTP VERSION 10 1000 
#define NGX HTTP VERSION 11 1001 





建议 使 用 http_version 分 析 HTTP 的 协议 版 本 。 : 
DDN Pttp' www inuxorobe. con 





最 后 ， 使 用 request_start 和 request_end 可 以 获取 原始 的 用 户 请 求 行 。 


3.6.3 ”获取 HTTP 头 部 








在 ngx_http_request_ttr 中 就 可 以 取 到 请 求 中 的 HITP 头 部 ， 比 如 使 用 下 面 的 成 员 : 





struct ngx http request s { 


ngx buf t *header in; ngx http headers in t headers in … 





其 中 ，header in 指 癌 Nginx 收 到 的 未 经 解析 的 HITP 头 部 ， 这 里 暂 不 关注 它 〈 在 第 11 章 中 
可 以 看 到 ，header in 就 是 接收 HTTP 头 部 的 缓冲 区 ) 。ngx_http_headers_in t 类 型 的 headers in 
则 存储 已 经 解析 过 的 HITP 头 部 。 下 面 介 绍 ngx_ http headers_in t 结 构 体 中 的 成 员 。 








typedef struct { 


/* 所 有 解析 过 的 
HTTP 头 部 都 在 


headers 链 表 中 ， 可 以 使 用 


和 生生 全 和 和 中 站 http:/ /ww | i nNuxporobe. con 





HTTP 头 部 。 注 意 ， 这 里 


headers 链 表 的 每 一 个 元 素 都 是 


ngx table elt 七 成 员 


* 


ngx list 七 headers; /* 以 下 每 个 


ngx_table elt 七 成 员 都 是 


RFC2616 规 范 中 定义 的 


HTTP 头 部 ， 


它们 实际 都 指向 


headers 链 表 中 的 相应 成 员 。 注 意 ， 当 它们 为 
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NUIL 空 指针 时 ， 表 示 没 有 解析 到 相应 的 


HTTP 头 部 


ngx table elt t 


ngx table elt t 


ngx table elt t 


#if (NGX HTTP REALIP) 





ngx table elt 














ERS) 





#if (NGX HTTP HEAD 





ngx table elt t 


#if (NGX HTTP DAV) 


ngx table elt t 


/*user 和 


passwd 是 只 有 


B24 


*host; ngx table elt t 


*accept encoding; ngx table elt t 


*authorization; ngx table elt t 


*x real ip; #endif 


*accept; ngx table elt t 


*depth; ngx table elt t 


ngx http auth basic moqule 才 会 用 到 的 成 员 ， 这 里 可 以 忽略 





ngx_ str 七 


*y 


user; ngx str t 


*connection; ngx table elt 七 


*via; #endif 


*keep alive; #if (NGX HTT 


*accept language; #endif 


*destination; ngx table elt t 


passwd; /*cookies 是 以 
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ngx array 鞋 数组 存储 的 ， 本 章 先 不 介绍 这 个 数据 结构 ， 感 兴趣 的 话 可 以 直接 跳 到 


ngx array 七 的 相关 用 法 


wy 
ngx array t cookies; // server 名 称 
Te er ae server; // 根据 
ngx table elt t *content length 计 算出 的 
HTTP 包 体 大 小 
off t content length n; time t keep alive n; /*HTTP 过 





NGX http CONNECTION CLOSE 或 者 
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NGX HTTP CONNECTION KEEP ALIVE*/ 








unsigned connection type:2; /* 以 下 


7 个 标志 位 是 


HTTP 框 架 根据 浏览 器 传 来 的 “ 


useragent” 头 部 ， 它 们 可 用 来 判断 浏览 器 的 类 型 ， 值 为 


1 时 表示 是 相应 的 浏览 器 发 来 的 请 求 ， 值 为 


0 时 则 相反 


发 / 


unsigned msie:1; unsigned msie6:1; unsigned 





获取 HTTP 头 部 时 ， 直 接 使 用 r->>headers_in 的 相应 成 员 就 可 以 了 。 这 里 举例 说 明 一 下 如 何 
通过 遍历 headers 链 表 获 取 非 RFC2616 标 准 的 HITP 头 部 ， 读 者 可 以 先 回 顾 一 下 ngx list t 链 表 
和 和 ngx_table_elt t 结 构 体 的 用 法 。 前 面 3.2.3 节 中 已经 介绍 过 ，headers 是 一 个 ngx list t 链 表 ， 写 
存储 着 解析 过 的 所 有 HTTP 尖 部 ， 链 表 中 的 元 素 都 是 ngx_table_elt t 类 型 。 下 而 尝试 在 一 个 用 
户 请 求 中 找到 “了 pc-Descriptionm 头 部 ， 首 先 判断 其 值 是 否 为 “uploadFile”， 再 决定 后 续 的 服务 
器 行为 ， 代 码 如 下 。 





"gx 平生 :本 下 站 :十 蔬 咱 二 [te °=rehtt fy /VE 上 PEXBFobeeoOf 





for (i = 0; /* void */; i++) { 


// 判断 是 否 到 达 链 表 中 当前 数组 的 结尾 处 


if (i >= part->nelts) { 


// 是 否 还 有 下 一 个 链表 数组 元 素 


if (part->next == NULL) { 


break; 


/* part 设 置 为 


next 来 访问 下 一 个 链表 数组 ; 


header 也 指向 下 一 个 链表 数组 的 首 地 址 ; 


i 设置 为 


0 时 ， 表 示 从 头 开 始 遍 历 新 的 链表 数组 
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part = part->next; 


header = part->elts; 


// hash 为 


0 时 表示 不 是 合法 的 头 部 


if (header[il].hash == 0) { 


continue; 


/* 判 断 当 前 的 头 部 是 否 是 


Rpc-Description”。 如 果 想 要 忽略 大 小 写 ， 则 应 该 先 用 


header[i] .lowcase key 代 痊 


header[i] .key.data， 然 后 比较 字符 串 


*/ 





== ngx strncasecmp (headerl[i].key.data, (u char*) "Rpc-Description", header[i].key.1len) 


让 中 让 中 让 站 站 本 








// 判断 这 个 


HTTP 头 部 的 值 是 否 是 “ 


uploadFile” 


if (0 == ngx strncmp (header[i] .value.data, "uploadFile", 


header[i] .value.1len)) 


// 找到 了 正确 的 头 部 ， 继 续 向 下 执行 





对 于 常见 的 HITP 头 部 ， 直 接 获 取 r->headers in 中 已 经 由 HTTP 框 架 解析 过 的 成 员 即 可 ， 
而 对 于 不 常见 的 HTTP 头 部 ， 需 要 裔 历 r->headers in.headers 链 表 才 能 获得 。 





3.6.4 获取 HITP 包 体 





HITP 包 体 的 长 度 有 可 能 非常 大 ， 如 果 试 图 一 次 性 调用 并 读 取 完 所 有 的 包 体 ， 那 么 多 半 
会 阻 突 Nginx 进 程 。HTTP 框 架 提 供 了 一 种 方法 来 异步 地 接收 包 体 : 
DODDDDDDDDDD ot Dy: AAA | 1 











ngx _ int t ngx http read client request bodqy (ngx httpP request t *r, ngx http client body handler pt post handler 











ngx_http_read_client request_body 是 一 个 异步 方法 ， 调 用 它 只 是 说 明 要 求 Nginx 开 始 接收 
请 求 的 包 体 ， 并 不 表示 是 否 已 经 接收 完 ， 当 接收 完 所 有 的 包 体内 容 后 ，post_handler 指 向 的 回 
调 方法 会 被 调用 。 因 此 ， 即 使 在 调用 了 ngx http read client request body 方 法 后 它 已 经 返回 ， 
也 无 法 确定 这 时 是 否 已 经 调用 过 post_handler 指 向 的 方法 。 换 句 话说 ， 
ngx_http_read_client request_ body 返回 时 既 有 可 能 已 经 接收 完 请 求 中 所 有 的 包 体 〈 假 如 包 体 的 
长 度 很 小 ) ， 也 有 可 能 还 没 开 始 接收 包 体 。 如 果 ngx http read_ client request body 是 在 
ngx_http_mytest_ handler 处 理 方法 中 调用 的 ， 那 么 后 者 一 般 要 返回 NGX_DONE， 因 为 下 一 步 融 
是 将 它 的 返回 值 作为 参数 传 给 ngx http finalize request。NGX _ DONE 的 意义 在 3.6.1 节 中 已 经 
介绍 过 ， 这 里 不 再 袭 述 











下 面 看 一 下 包 体 接收 完毕 后 的 回调 方法 原型 ngx http_client body handler pt 是 如 何 定义 





typedef void (*ngx http client body handler pt) (ngx http request t *r); 








其 中 ， 有 参数 ngx_http_ request_ ttr， 这 个 请 求 的 信息 都 可 以 从 r 中 获得 。 这 样 可 以 定义 一 
个 方法 void func(ngx http request t*r)， 在 Nginx 接 收 完 包 体 时 调用 它 ， 男 外 ， 后 续 的 流程 也 都 
会 写 在 这 个 方法 中 ， 例 如 : 








void ngx http mytest body handler (ngx http request 七 *r) { 








@ 注意。 nex_http_mytest_ body_ handler 的 返回 类 型 是 void，Nginx 不 会 根据 返回 值 做 一 些 
收尾 工作 ， 因 此 ， 我 们 在 该 方法 里 处 理 完 请 求 时 必须 要 主动 调用 ngx_http_finalize_request 方 法 
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来 结束 请 求 。 


接收 包 体 时 可 以 这 样 写 : 





ngx int t rc = ngx http read client request bodyl(r, ngx http mytest body handler); if (rc >= NGX HTTP SPECIAL RI 














return re; 


return NGX DONE; 











Nginx 寞 步 接收 HTTP 请 求 的 包 体 的 内 容 将 在 11.8 节 中 详 述 。 


如 果 不 想 处 理 请 求 中 的 包 体 ， 那 么 可 以 调用 ngx_ http_ discard _ request body 方法 将 接收 自 
客户 问 的 HITP 包 体 丢 弃 反 。 例 如 : 





ngx int t rc = ngx http discard request body(r); if (rc != NGX OK) { 


return re; 








ngx_http_discard request body 只 是 丢弃 包 体 ， 不 处 理 包 体 不 束 行 了 吗 ? 何 必 还 要 调用 
ngx http_discard_request_body 方 法 呢 ? 其 实 这 一 步 非 常 有 意义 ， 因 为 有 些 客 户 端 可 能 会 一 直 
试图 发 送 包 体 ， 而 如 果 HTTP 模 块 不 接收 发 来 的 TCP 流 ， 有 可 能 造成 客户 端 及 送 超 时 。 


接收 完 请 求 的 包 体 后 ， 可 以 在 r->request_body->temp file->file 中 获取 临时 文件 (假定 将 r- 
>request_body_in file_only 标 志 位 设 为 1!， 那 就 一 定 可 以 在 这 个 变量 获取 到 包 体 。 更 复杂 的 接 
收 包 体 的 方式 本 节 暂 不 讨论 ) 。fle 是 一 个 ngx file t 类 型 ， 在 3.8 节 会 详细 介绍 它 的 用 法 。 这 
里 ， 我 们 可 以 从 r->request body->temp file->file.name 中 获取 Nginx 接 收 到 的 请 求 包 体 所 在 文件 

nn httpo://wWw linuxorobe.con 








的 名 称 〈 包 括 路 径 ) 。 
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3.7 ”发 送 啊 应 


请 求 处 理 完毕 后 ， 需 要 向 用 户 发 送 HTTP 响 应 ， 告 知客 户 端 Nginx 的 执行 结果 。HTTP 响 
应 主要 包括 响应 行 、 响 应 头 部 、 包 体 三 部 分 。 发 送 HTTP 响 应 时 需要 执行 发 送 HTTP 头 部 (发 
送 HTTP 头 部 时 也 会 发 送 响应 行 ) 和 发 送 HTTP 包 体 两 步 操作 。 本 节 将 以 发 送 经 典 的 “Hello 
World” 为 例 来 说 明 如 何 发 送 啊 应 。 





3.7.1 发送 HTTP 头 部 


下 和 面 看 一 下 HTTP 框 架 提 供 的 发 送 HTTP 头 部 的 方法 ， 如 下 所 示 。 





ngx int t ngx http send header (ngx http request 七 *r); 








调用 ngx http send header 时 把 ngx http request {对象 传 给 它 即 可 ， 而 ngx http send header 
的 返回 值 是 多 样 的 ， 在 本 节 中 ， 可 以 认为 返回 NGX_ERROR 或 返回 值 大 于 0 就 表示 不 正常 ， 
例如 : 











ngx int t rc = ngx http send header(r); if (rc == NGX ERROR || rc > NGX OK || r->header only) { 


return rc; 





下 面 介 绍 设置 啊 应 中 的 HITP 头 部 的 过 程 。 


如 同 headers in，ngx http request t 也 有 一 个 headers_out 成 员 ， 用 来 设置 啊 应 中 的 HITP 头 
部 ， 如 下 所 示 。 
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ngx http headers in t headers in; ngx http headers out t headers out; … 





只 要 指定 headers_out 中 的 成 员 ， 就 可 以 在 调用 ngx http send header 时 正确 地 把 HTTP 头 部 
发 出 。 下 面 介绍 headers_out 的 结构 类 型 ngx_http_headers_out t。 





typedef struct { 


// 待 发 送 的 


HTTP 头 部 链表 ， 与 


headers in 中 的 


headers 成 员 类 似 


ngx list 七 headers; /* 响 应 中 的 状态 值 ， 如 


200 表 示 成 功 。 这 里 可 以 使 用 


口 由 掉 岂 有 有 和 所 掉 由 http' /wNv inuxorobe. con 





NGX_HTTP OK */ 


ngx uint 七 status; // 响应 的 状态 行 ， 如 “ 








HTTP/1.1 201 CREATED 








ngx str t status line; /* 以 下 成 员 (包括 


ngx table elt 七 ) 都 是 


RFC1616 规 范 中 定义 的 


HTTP 头 部 ， 设 置 后 ， 


ngx http header filter module 过 滤 模 块 可 以 把 它们 加 到 待 发 送 的 网 络 包 中 





2 


ngx table elt t *server; ngx table elt t *date; ngx table elt 七 





ngx http set content type(r) 方 法 帮助 我 们 设置 
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Content-Type 头 部 ， 这 个 方法 会 根据 


URI 中 的 文件 扩展 名 并 对 应 着 


mime .type 来 设置 


Content-Type 值 


x/ 
S 主 Be 蕊 content type len; ngx str 七 content type; ngx_ str 
content length n 后 ,， 不 用 再 次 到 
ngx table elt 七 *content length 中 设置 响应 长 度 
*/ 
(ob Ms content length n; time t date time; time t 





在 癌 headers 链 表 中 添加 目 定 义 的 HITP 头 部 时 ， 可 以 参考 3.2.3 节 中 nsgx_ list push 的 使 用 方 
法 。 这 里 有 一 个 简单 的 例子 ， 如 下 所 示 。 





ngx table elt tx h = ngx list push(&r->headers out.headers); if (h == NULL) { 





return NGX ERROR; 
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h->hash = 1; 








h->key.len = sizeof ("TestHead") - 1; 
h->key.data = (u char *) "TestHead"; 
h->value.len = sizeof("TestValue") - 1; h->value.data = (u char *) "TestValue"; 





这 样 将 会 在 啊 应 中 新 增 一 行 HTTP 头 部 : 





TestHead: TestValue\r\n 











如 条 发 送 的 是 一 个 不 含有 HTTP 包 体 的 啊 应 ， 这 时 就 可 以 直接 结束 请 求 了 《例如 ， 在 
ngx_http_ mytest handler 方 法 中 ， 直 接 在 ngx http send _ header 方法 执行 后 将 其 返回 值 return 即 
司 


@ 注意 ngx_http_send_headet 方 法 会 首先 调用 所 有 的 HTTP 过 滤 模块 共同 处 理 
headers_out 中 定义 的 HTTP 响 应 头 部 ， 全 部 处 理 完毕 后 才 会 序列 化 为 TCP 字 符 流 发 送 到 客户 


端 ， 相 关 流 程 可 参见 11.9.1 节 。 





3.7.2 ”将 内 存 中 的 字符 串 作 为 包 体 发 送 


调用 ngx_http_output filter 方 法 即 可 回 客 户 端 发 送 HTTP 啊 应 包 体 ， 下 面 得 看 一 下 此 方法 的 
原型 ， 如 下 所 示 。 





ngx int t ngx http output filter(ngx http request t r, ngx chain t in); 








ngx_http_output_filter 的 返回 值 在 mytest 例 子 中 不 需要 处 理 ， 通 过 在 ngx_http_mytest_handler 
方法 中 返回 的 方式 传递 给 ngx http finalize request 即 可 。ngx _chain t 结 构 已 经 在 3.2.6 节 中 介绍 


过 ， 它 种 则 六 守 他 tp 几 斩 i” 下 以 雷 虽 全 7 ON lp PE 四 内 雁 。 下面 








介绍 Nginx 的 内 存 池 是 如 何 分 配 内 存 的 。 


为 了 减少 内 存 碎片 的 数量 ， 并 通过 统一 管理 来 减少 代码 中 出 现 内 存 泄漏 的 可 能 性 ， 
Nginx 设 计 了 ngx pool { 内 存 池 数 据 结构 。 本 章 我 们 不 会 深入 分 析 内 存 池 的 实现 ， 只 关注 内 存 
池 的 用 法 。 在 ngx_ http mytest handler 处 理 方法 传 来 的 ngx_http_ request t 对 象 中 就 有 这 个 请 求 的 
内 存 池 管理 对 象 ， 我 们 对 内 存 池 的 操作 都 可 以 基于 它 来 进行 ， 这 样 ， 在 这 个 请 求 结束 的 时 
候 ， 内 存 池 分 配 的 内 存 也 都 会 被 释放 。 








struct ngx http request s { 


ngx pool 七 *pool; 








实际 上 ， 在 r 中 可 以 获得 许多 内 存 池 对 象 ， 这 些 内 存 池 的 大 小 、 意 义 及 生存 期 各 不 相 
同 。 第 3 部 分 会 涉及 许多 内 存 池 ， 本 章 使 用 r->pool 内 存 池 即 可 。 有 了 ngx pool {对 象 后 ， 可 以 
从 内 存 池 中 分 配 内 存 。 例 如 ， 下 面 这 个 基本 的 申请 分 配 内 存 的 方法 : 


void xngx Palloc (ngx pool t *pool, size t size); 


其 中 ，ngx_palloc 函 数 将 会 从 pool 内 存 池 中 分 配 到 size 字 节 的 内 存 ， 并 返回 这 段 内 存 的 起 
始 地 址 。 如 果 返 回 NULL 空 指针 ， 则 表示 分 配 失败 。 还 有 一 个 封装 了 ngx_palloc 的 函数 
ngx pcalloc， 它 多 做 了 一 件 事 ， 就 是 把 ngx palloc 申 请 到 的 内 存 块 全 部 置 为 0， 虽 然 ， 多 数 情 
况 下 更 适合 用 ngx_pcalloc 来 分 配 内 存 。 
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假如 要 分 配 一 个 ngx_buf t 结 构 ， 可 以 这 样 做 : 





ngx buf tx b = ngx pcalloc(r->pool, sizeof (ngx buf 七 ) ) ; 








这 样 ，ngx_buf t 中 的 成 员 指 向 的 内 存 仍 然 可 以 继续 分 配 ， 例 如 : 





b->start = (u char*)ngx pcalloc(r->pool, 128); b->pos = b->start; 


b->last = b->start; 


b->end = b->last + 128; 


b->temporary = 1; 








实际 上 ，Nginx 还 封装 了 一 个 生成 ngx buf t 的 简便 方法 ， 它 完全 等 价 于 上 面 的 6 行 语句 ， 
如 下 所 示 。 





ngx buf t *b = ngx create temp buf(r->pool, 128); 








分 配 完 内 存 后 ， 可 以 向 这 段 内 存 写 入 数据 。 当 写 完 数据 后 ， 要 让 b->last 指 针 指 癌 数 据 的 
末尾 ， 如 果 b->last 与 b->pos 相 等 ， 那 么 HTTP 框 架 是 不 会 发 送 一 个 字 节 的 包 体 的 。 





最 后 ， 把 上 面 的 ngx buf txb 用 ngx_ chain t 传 给 ngx http_output filter 方 法 就 可 以 发 送 HTTP 
啊 应 的 包 体 内 容 了。 例如 : 





ngx chain t out; 


out.buf = b; 


out.next = NULL; 


return ngx http output filter(r, &out); 
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@@ 注意 在 向 用 户 发 送 响应 包 体 时 ， 必 须 牢 记 Nginx 是 全 异步 的 服务 器 ， 也 就 是 说 ， 不 
可 以 在 进程 的 栈 里 分 配 内 存 并 将 其 作为 包 体 发 送 。 当 一 直 ngx_http_output filter 方法 返回 时 ， 
可 能 由 于 TCP 连 接 上 的 缓冲 区 还 不 可 写 ， 所 以 导致 ngx_buf t 缓 冲 区 指向 的 内 存 还 没有 发 送 ， 
可 这 时 方法 返回 已 把 控制 权 交 给 Nginx 了 ， 又 会 导致 栈 里 的 内 存 被 释放 ， 最 后 就 会 造成 内 存 
越界 错误 。 因 此 ， 在 发 送 响 应 包 体 时 ， 尽 量 将 ngx_buf_t 中 的 pos 指 针 指 向 从 内 存 池 里 分 配 的 
内 存 。 


3.7.3 经 典 的 “Hello World”* 示 例 


下 面 以 经 典 的 返回 “Hello World” 为 例 来 编写 一 个 最 小 的 HTTP 处 理 模 块 ， 以 此 介绍 完整 
的 ngx http mytest handler 处 理 方法 。 





static ngx int t ngx http mytest handler (ngx http request t *r) { 





// 必须 是 


GET 或 者 








HEAD 方 法 ， 否 则 返回 


405 Not Allowed 


if (!(r->method & (NGX HTTP GETINGX HTTP HEAD))) { 








return NGX HTTP NOT ALLOWED; 





// 丢弃 请 求 中 的 包 体 
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ngx int t rc = ngx http discard request body(r); if (rc != NGX OK) { 


return rc; 


/* 设 置 返回 的 


Content-Type。 注 意 ， 


ngx_str tt 有 一 个 很 方便 的 初始 化 宏 


ngx _ string， 它 可 以 把 


ngx _ str 七 的 
data 和 
len 成 员 都 设置 好 
EA 
ngx_ str 七 type = ngx string("text/plain"); // 返回 的 包 体 内 容 
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r->headers out.status = NGX HTTP OK; // 响应 包 是 有 包 体 内 容 的 ， 需 要 设置 


Content-Length 长 度 


r->headers out.content length n = response.len; // 设置 


Content-Type 





r->headers out.content type = type; // 发 送 


HTTP 头 部 


rc = ngx http send header (r); 





if (rc == NGX ERROR || rc > NGX OK || r->header only) { 


return rc; 


// 构造 


ngx_buf 七 结构 体 准 备 发 送 包 体 


口 由 掉 岂 有 所 和 所 掉 由 http' /wNv inuxorobe. con 





ngx buf 七 *b; 


b = ngx create temp buf(r->pool, response.len); if (b == NULL) { 








return NGX HTTP INTERNAL SERVER ERROR; } 














// 将 


Hello World 复 制 到 


ngx buf 七 指向 的 内 存 中 


ngx memcpy(b->pos，response.data，response.len); // 注意 ， 一 定 要 设置 好 


last 指 针 


b->last = b->pos + response.len; // 声明 这 是 最 后 一 块 缓冲 区 


b->last buf = 1; 


// 构造 发 送 时 的 


ngx chain 鞋 结构 体 


TiNNinNnnn http://wWwWw linuxorobe.con 





ngx chain t out; 


// 赋值 


ngx buf t 


out .buf = b; 


// 设置 


next 为 


NULL 


out.next = NULL; 


HTTP 框 架 会 调用 


ngx http finalize request 方 法 结束 请 求 


*y/ 


return ngx http output filter(r, &out); } 
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3.8 ”将 磁盘 文件 作为 包 体 发 送 


上 文 讨论 了 如 何 将 内 存 中 的 数据 作为 包 体 发 送 给 客户 闫 ， 而 在 发 送 文件 时 完全 可 以 先 把 
文件 读 取 到 内 存 中 再 向 用 户 发 送 数据 ， 但 是 这 样 做 会 有 两 个 缺点 : 





` 为 了 不 阻塞 Nginx， 每 次 只 能 读 取 并 发 送 磁盘 中 的 少量 数据 ， 需 要 反复 持续 多 次 。 


Linux 上 高 效 的 sendfile 系 统 调用 不 需要 先 把 磁盘 中 的 数据 读 取 到 用 户 态 内 存 再 发 送 到 








当然 ，Nginx 已 经 封闭 好 了 多 种 接口 ， 以 便 将 磁盘 或 者 缓存 中 的 文件 发 送 给 用 户 。 





3.8.1 如何 发 送 磁 盘 中 的 文件 


发 送 文件 时 使 用 的 是 3.7 节 中 所 介绍 的 接口 。 例 如 : 





ngx chain t out; 


out.buf = b; 


out.next = NULL; 


return ngx http output filter(r, &out); 





两 者 不 同 的 地 方 在 于 如 何 设置 ngx_buf t 绥 冲 区 。 在 3.2.5 节 中 介绍 过 ，ngx_buf t 有 一 个 标 
志 位 in file， 将 in fle 置 为 1 就 表示 这 次 ngx_buf t 退 冲 区 发 送 的 是 文件 而 不 是 内 存 。 调 用 
ngx_http_output filter 后 ， 若 Nginx 检 测 到 in_file 为 1， 将 会 从 ngx_buf t 绥 冲 区 中 的 file 成 员 处 获 
取 实 际 的 文件 。file 的 类 型 是 ngx file t， 下 面 看 一 下 ngx file t 的 结构 。 





typedef struct ngx file s ngx file t; struct ngx file s { 
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// 文件 句柄 描述 符 


ngx fd 七 fd; 


// 文件 名 称 


ngX_Stt t name; 


// 文件 大 小 等 资源 信息 ， 实 际 就 是 


Linux 系 统 定 义 的 


stat 结 构 


ngx file info t info; 


/* 该 偏 移 量 告诉 


Nginx 现 在 处 理 到 文件 何 处 了 ， 一 般 不 用 设置 它 ， 


Nginx 框 架 会 根据 当前 发 送 状态 设置 它 
sy 


off 七 offset; 
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// 当前 文件 系统 偏 移 量 ， 一 般 不 用 设置 它 ， 同 样 由 


Nginx 框 架设 置 


off 七 sys offset; 


// 日 志 对 象 ， 相 关 的 日 志 会 输出 到 


log 指 定 的 日 志文 件 中 


ngx log 七 *]log; 


// 目前 未 使 用 


unsigned validqd info:1; 


// 与 配置 文件 中 的 


directio 配 置 项 相对 应 ， 在 发 送 大 文件 时 可 以 设 为 


unsigned directio:1; 
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fd 是 打开 文件 的 句柄 描述 符 ， 打 开 文 件 这 一 步 需要 用 户 自 己 来 做 。Nginx 人 简单 封 疲 了 一 个 
宏 用 来 代替 open 系 统 的 调用 ， 如 下 所 示 。 








#define ngx open file(name, mode, create, access) \ 


open((const char *) name, mode|create, access) 








实际 上 ，ngx_open file 与 open 方 法 的 区 别 不 大 ，ngx_open file 返 回 的 是 Linux 系 统 的 文件 
句柄 。 对 于 打开 文件 的 标志 位 ，Nsginx 也 定义 了 以 下 几 个 宏 来 加 以 封装 。 








#define NGX FILE RDONLY O RDONLY 


#define NGX FILE WRONLY O WRONLY 





#define NGX FILE RDWR O RDWR 





#define NGX FILE CREATE OR OPEN O CREAT 



































#define NGX FILE OPEN 0 





#define NGX FILE TRUNCATE O CREAT|O TRUNC 



































#define NGX FILE APPEND O WRONLY|O APPEND 








#define NGX FILE NONBLOCK O NONBLOCK 


























#define NGX FILE DEFAULT ACCESS 0644 





#define NGX FILE OWNER ACCESS 0600 

















因此 ， 在 打开 文件 时 只 需要 把 文件 路 径 传 递 给 name 参 数 ， 并 把 打开 方式 传递 给 mode、 
create、access 参 数 即 可 。 例 如 : 





ngx buf 七 *b; 
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b = ngx palloc(r->pool, sizeof (ngx buf t)); u charx filename = (u char*)"tmptest.txt"; b->in file = 1; 


b->file = ngx pcalloc(r->pool, sizeof (ngx file t+)); b->file->fd = ngx open filel(filename, NGX FILE RDONLY|NGX 下- 








b->file->name.len = strlen(filename); if (b->file->fd <= 0) 





return NGX HTTP NOT FOUND; 











到 这 里 其 实 还 没有 结束 ， 还 需要 告知 Nginx 文 件 的 大 小 ， 包 插 设 置 啊 应 中 的 Content- 
Length 尖 部， 以 及 设置 ngx buf t 组 冲 区 的 fle pos 和 file last。 实 际 上 ， 通 过 ngx file tt 结构 里 
ngx _ file info {类 型 的 info 变 量 就 可 以 获取 文件 信息 : 








typedef struct stat ngx file info t; 





Nginx 不 只 对 stat 数 据 结构 做 了 封装 ， 对 于 由 操作 系统 中 获取 文件 信息 的 stat 方 法 ，Nginx 
也 使 用 一 个 宏 进 行 了 简单 的 封闭， 如 下 所 示 : 





#define ngx file info(file，sb) stat((const char *) file, sb) 





因此 ， 获 取 文 件 信 息 时 可 以 先 这 样 写 : 








if (ngx file infol(filename, &b->file->info) == NGX FILE ERROR) { 














return NGX HTTP INTERNAL SERVER ERROR; } 




















之 后 必须 要 设置 Content-Length 头 部 : 








r->headers out.content length n = b->file->info.st size; 
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还 需要 设置 ngx_buf t 组 冲 区 的 fle pos 和 file last: 





b=>f1ile: pos 三 7 


b->file last = b->file->info.st size; 





这 里 是 告诉 Nginx 从 文件 的 fle_pos 偏 移 量 开始 发 送 文 件 ， 一 直到 达 file_last 偏 移 量 处 截 
让 


人 注意 当 磁 盘 中 有 大 量 的 小 文件 时 ， 会 占用 Linux 文 件 系统 中 过 多 的 inode 结 构 ， 这 
时 ， 成 熟 的 解决 方案 会 把 许多 小 文件 合并 成 一 个 大 文件 。 在 这 种 情况 下 ， 当 有 需要 时 ， 只 要 
把 上 面 的 fle bos 和 file last 设 置 为 合适 的 偏 移 量 ， 就 可 以 只 发 送 合并 大 文件 中 的 某 一 块 内 容 
(原来 的 小 文件 ) ， 这 样 就 可 以 大 幅 降 低 小 文件 数量 。 


3.8.2 ”清理 文件 句柄 


Nginx 会 异步 地 将 整个 文件 高 效 地 发 送 给 用 户 ， 但 是 我 们 必须 要 求 HTTP 框 架 在 啊 应 发 送 
完毕 后 关闭 已 经 打开 的 文件 句柄 ， 人 否则 将 会 出 现 句柄 泄露 问题 。 设 置 清理 文件 句柄 也 很 简 
单 ， 只 需要 定义 一 个 ngx_ pool cleanup t 结 构 体 (这 是 最 简 蛙 的 方法 ，HTTP 框 染 还 提供 了 其 
他 方式 ， 在 请 求 结束 时 回调 各 个 HITP 模 块 的 cleanup 方 法 ， 将 在 第 11 章 介绍 ) ， 将 我 们 刚 得 
到 的 文件 句柄 等 信息 赋 给 它 ， 并 将 Nginx 提 供 的 ngx_pool_cleanup_file 函 数 设 置 到 它 的 handler 
回调 方法 中 即 可 。 首 先 介绍 一 下 ngx_pool_cleanup t 结 构 体 。 





typedef struct ngx pool cleanup s ngx pool cleanup t; struct ngx Pool cleanup s { 


// 执行 实际 清理 资源 工作 的 回调 方法 


ngx pool cleanup pt handler; 
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// handler 回 调 方法 需要 的 参数 


void *data; 


// 下 一 个 


ngx pool cleanup 清理 对 象 ， 如 果 没 有 ， 需 置 为 


NULL 


ngx pool cleanup 七 *next; 











设置 好 handler 和 data 成 员 就 有 可 能 要 求 HTTP 框 架 在 请 求 结 束 前 传 入 data 成 员 回 调 handler 
方法 。 接 着 ， 介 绍 一 下 专用 于 关闭 文件 句柄 的 ngx_ pool _ cleanup_file 方 法 。 





void ngx pool cleanup file(voiq *data) { 





ngx pool cleanup file t xc = data; ngx log debugl (NGX LOG DEBUG ALLOC, c->lo0g, 0, "file cleanup: fd:%d",c-: 





ngx log error(NGX LOG ALERT, c->log, ngx errno, ngx close file n " \"%s\" failed", c->name); } 





ngx_pool_cleanup file 的 作用 是 把 文件 句柄 关闭 。 从 上 面 的 实现 中 可 以 看 出 ， 
ngx pool cleanup file 方 法 需要 一 个 ngx pool cleanup file t 类 型 的 参数 ， 那 么 ， 如 何 提 供 这 个 
参数 呢 ? 在 ngx_pool_cleanup tt 结构 体 的 data 成 员 上 赋值 即 可 。 下 而 介绍 一 下 


ngx pool cleanup file t 的 结构 。 

















typedef struct { 


// 文件 句柄 


ngx fd 七 fd; 


// 文件 名 称 


u char *name; 


// 日 志 对 象 


ngx log 七 *1og7 


} ngx Pool cleanup file t; 





可 以 看 到 ，ngx pool_cleanup_file t 中 的 对 象 在 ngx_buf tt 绥 冲 区 的 fle 结 构 体 中 都 出 现 过 
了 ， 意 义 也 是 相同 的 。 对 于 file 结 构 体 ， 我 们 在 内 存 池 中 己 经 为 它 分 配 过 内 存 ， 只 有 在 请 求 
结束 时 才 会 释放 ， 因 此 ， 这 里 简单 地 引用 file 里 的 成 员 即 可 。 清 理 文 件 句 柄 的 完整 代码 如 
下 





ngx pool _ cleanup tx cln = ngx pool _ cleanup add(r->pool, sizeof (ngx pool _ cleanup file t+)); if (cln == NULL) { 


return NGX ERROR; 





cln->handler = ngx Pool cleanup file; ngx Pool cleanup file t xclnf = cln->data; clnf->fd = b->file->fqd; 
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clnf->name = b->file->name.data; clnf->log = r->poo0l->1log; 





ngx_pool_cleanup_add 用 于 告诉 HTTP 框 架 ， 在 请 求 结束 时 调用 cln 的 handler 方 法 清理 资 


至 此 ，HTTP 模 块 已 经 可 以 同 客 户 端 发 送 文 件 了 了。 下 面 介绍 一 下 如 何 支 持 多 线程 下 载 与 
断 点 续 传 。 


3.8.3 支持 用 户 多 线程 下 载 和 断 点 续 传 


RFC2616 规 范 中 定义 了 range 协 议 ， 它 给 出 了 一 种 规则 使 得 客户 端 可 以 在 一 次 请 求 中 只 下 
载 完 整 文件 的 系 一 部 分 ， 这 样 束 可 支持 客户 端 在 开局 多 个 线程 的 同时 下 载 一 份 文件 ， 其 中 每 
个 线程 仅 下 载 文件 的 一 部 分 ， 最 后 组 成 一 个 完整 的 文件 。range 也 支持 断 反 续 传 ， 只 要 客户 端 
记录 了 上 次 中 断 时 已 经 下 载 部 分 的 文件 念 移 量 ， 就 可 以 要 求 服务 器 从 断 点 处 发 送 文件 之 后 的 


内 容 。 





Nginx 对 range 协 议 的 支持 非常 好 ， 因 为 range 协 议 主要 增加 了 一 些 HITP 头 部 处 理 流程 ， 以 
及 发 送 文 件 时 的 偏 移 量 处 理 。 在 第 1 章 中 曾 说 过 ，Nginx 设 计 了 HTTP 过 滤 模 块 ， 每 一 个 请 求 
可 以 由 许多 个 HITP 过 滤 模 块 处理 ， 而 http range header filter 模 块 就 是 用 来 处 理 HTTP 请 求 头 
部 range 部 分 的 ， 它 会 解析 客户 端 请 求 中 的 range 头 部 ， 最 后 告知 在 发 送 HTTP 响 应 包 体 时 将 会 
调用 到 的 ngx_http_range_body filter_ module 模 块 ， 该 模块 会 按照 range 协 议 修改 指 疝 文件 的 
ngx_buf t 组 冲 区 中 的 fle pos 和 file last 成 员 ， 以 此 实现 仅 发 送 一 个 文件 的 部 分 内 容 到 客户 


、 


端 。 











其 实 ， 文 持 range 协 议 对 我 们 来 说 很 简单 ， 只 需要 在 发 送 前 设置 nex http request t 的 成 员 
allow_ ranges 变 量 为 ] 即 可 ， 之 后 的 工作 都 会 由 HTTP 框架 完成 。 例 如 : 





r->allow ranges = 1; 
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这 样 ， 我 们 就 文 持 了 多 线程 下 载 和 断 点 续 传 功能 。 
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3.9 ”用 C++ 语言 编写 HTTP 模 块 


Nginx 及 其 官方 模块 都 是 由 C 语 言 开 发 的 ， 那 么 能 不 能 使 用 C++ 语言 来 开 有 友 Nginx 模 块 呢 ? 
C 语 言 是 面向 过 程 的 编程 语言 ，C++ 则 是 面向 对 象 的 编程 语言 ， 面 向 对 象 与 面向 过 程 的 优 劣 
这 里 暂且 不 论 ， 存 在 即 合理 。 当 我 们 由 于 各 种 原因 需要 使 用 C++ 语言 实现 一 个 Nginx 模 块 时 
(例如 ， 茶 个 子 功能 是 用 C++ 语 言 写成 ， 或 者 开发 团队 对 C++ 语 言 更 熟练 ， 叉 或 者 束 是 豆 欢 
使 用 C++ 语言 ) ， 尽 管 Nginx 本 身 并 没有 提供 相应 的 方法 文 持 这 样 做 ， 但 由 于 C 语 言 与 C++ 语 
言 的 近 杀 特性 ， 我 们 还 是 可 以 比较 容易 达成 此 目的 的 。 














首先 需要 卉 清楚 相关 解决 方案 的 设计 思路 。 


不 要 试图 用 C++ 编译 器 〈 如 G++) 来 编译 Nginx 的 官方 代码 ， 这 会 带 来 大 量 的 不 可 控 
错误 。 正 确 的 做 法 是 仍然 用 C 编 译 器 来 编译 Nginx 官 方 提供 的 各 模块 ， 而 用 C++ 编译 器 来 编译 
用 C++ 语言 开发 的 模块 ， 最 后 利用 C++ 向 前 兼容 C 语 言 的 特性 ， 使 用 C++ 编译 器 把 所 有 的 目 
标 文 件 链接 起 来 〈 包 括 C 编 译 器 由 Nginx 人 官方 模块 生成 的 目标 文件 和 C++ 编译 器 由 第 三 方 模块 
生成 的 目标 文件 ) ， 这 样 才 可 以 正确 地 生成 二 进 制 文件 Nginx。 


保证 C++ 编译 的 Nginx 模 块 与 C 编 译 的 Nginx 模 块 互 相 适 应 。 所 谓 互相 适应 就 是 C++ 模 
块 要 能 够 调用 Nginx 框 架 提 供 的 C 语 言 方法 ， 而 Nginx 的 HITP 框 架 也 要 能 够 正常 地 回调 C++ 模 
块 中 的 方法 去 处 理 请 求 。 这 一 点 用 C++ 提供 的 extetn “C” 特 性 即 可 实现 。 





下 面 详 述 如 何 实现 上 述 两 点 内 容 。 


3.9.1 编译 方式 的 修改 








Nginx 的 configure 脚 本 没有 对 C++ 语 言 编译 模块 提供 支持 ， 因 此 ， 修 改编 译 方式 就 有 以 下 
两 种 思路 : 
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1) 修改 configure 相 关 的 脚本 。 


2) 修改 configure 执 行 完毕 后 生成 的 Makefile 文 件 。 





我 们 推荐 使 用 第 2 种 方法 ， 因 为 Nginx 的 一 个 优点 是 具备 大 量 的 第 三 方 模块 ， 这 些 模块 都 
是 基于 官方 的 configure 脚 本 而 写 的 ， 擅 上 自修 改 configure 脚 本 会 导致 我 们 的 Nginx 无 法 使 用 第 三 
方 模块 。 

修改 Makefile 其 实 是 很 简单 的 。 首 先 我 们 根据 3.3.2 节 介绍 WE 
之 后 会 生成 objs Makefile 文 件 ， 此 时 只 需要 修改 这 个 文件 的 3 处 即 可 实现 C++ 模块 。 这 里 还 是 
以 mytest 模 块 为 例 ， 代 码 如 下 。 





CC = kaie 

CXX = g++ 

CFLAGS = -pipe -0 -W -Wall -Wpointer-arith -Wno-unused-parameter -Wunused-function -Wunused-variable -Wunused 
GPP = ee = 





LINK = $ (CXX).… 





objs/addon/httpmodule/ngx http mytest module.o: $(ADDON DEPS) \ 
../sample/httpmodule/ngx http mytest module.c 
$ (CXX) -C $(CFLAGS) $ (ALL INCS) \\ 
-oO objs/addon/nttpmodule/ngx nttp mytest module.o \ 
../sample/httpmodule/ngx http mytest module.cpp… 








下 面 解释 一 下 上 述 代 码 中 修改 的 地 方 。 
. 在 Makefile 文 件 首部 新 增 了 一 行 CXX=g++， 即 添加 了 C++ 编 译 器 。 
把 链接 方式 LINK=$(CC) 改 为 了 LINK=$(CXX) ， 表 示 用 C++ 编译 器 做 最 后 的 链接 。 


. 把 模块 的 编译 方式 修改 为 C++ 编译 器 。 如 果 我 们 只 有 一 个 C++ 源 文件 ， 则 只 要 修改 一 
处 ， 但 如 果 有 多 个 C++ 源 文件 ， 则 每 个 地 方 都 需要 修改 。 修 改 方式 是 把 $(CC) 改 为 $(CXXI)。 








这 样 ， 编 详 方式 即 修改 完毕 。 修 改 源 文件 后 不 要 轻易 执行 configure 脚 本 ， 人 否则 会 履 兰 已 


经 修改 过 的 Makefile。 建 议 将 修改 过 的 Makefile 文 件 进行 备份 ， 避 免 每 次 执行 configure 后 重新 
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修改 Makefile。 


@ 注意 “确保 在 操作 系统 上 已 经 安装 了 C++ 编译 器 。 请 参照 1.3.2 节 中 的 方式 安装 gcc- 


c 十 十 编译 器 。 


3.9.2 ”程序 中 的 符号 转换 





C 语 言 与 C++ 语言 最 大 的 不 同 在 于 编译 后 的 符 写 有 差别 《C++ 为 了 支持 多 种 面向 对 象 特 
性 ， 如 重 载 、 类 等 ， 编 译 后 的 方法 名 与 C 语 言 完全 不 同 ) ， 这 可 以 通过 C++ 语言 提供 的 
extern“C”{} 来 实现 符号 的 互相 识别 。 也 就 是 说 ， 在 C++ 语 言 开 发 的 模块 中 ，include 包 含 的 
Nginx 官 方 头 文 件 都 需要 使 用 externC" 括 起 来 。 例 如 : 








extern "C" { 
#include <ngx config.h> 
#include <ngx core.h> 
#include <ngx http.h> 

} 





这 样 就 可 以 正 毅 地 调用 Nginx 的 各 种 方法 了 。 


另外 ， 对 于 希望 Neginx 框 架 回 调 的 类 似 于 ngx _ http mytest handler 这 样 的 方法 也 需要 放 在 


extern’C”* 中 。 
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3.10 小结 


本 章 讲 述 了 如 何 开 发 一 个 基本 的 HTTP 模块 ， 这 里 除了 获取 请 求 的 包 体 外 没有 涉及 异步 
处 理 问 题 。 通 过 本 章 的 学 习 ， 读 者 应 该 可 以 轻松 地 编写 一 个 简单 的 HTTP 模 块 了 ， 既 可 以 获 
取 到 用 户 请 求 中 的 任何 信息 ， 也 可 以 发 送 任意 的 响应 给 用 户 。 当 然 ， 处 理 方法 必须 是 快速 、 
无 阻塞 的 ， 因 为 Nginx 在 调用 例子 中 的 ngx http mytest handler 方 法 时 是 阻塞 了 整个 Nginx 进 程 
的 ， 所 以 ngx_http_mytest_ handler 或 类 似 的 处 理 方法 中 是 不 能 有 耗 时 很 长 的 操作 的 。 
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第 4 和 章 ”配置 、error 日 志和 请 求 上 下 文 





在 开发 功能 灵活 的 Nginx 模 块 时 ， 需 要 从 配置 文件 中 获取 特定 的 信息 ， 不 过 ， 不 需要 再 
编写 一 套 读 取 配置 的 系统 ，Nginx 已 经 为 用 户 提供 了 强大 的 配置 项 解析 机 制 ， 同 时 它 还 文 持 “- 
s reload” 命 令 一 一 在 不 重启 服务 的 情况 下 可 使 配置 生效 。4.1 节 会 回顾 第 2 半 中 http 配 置 项 的 一 
些 特点 ，4.2 节 中 会 全 面 讨论 如 何 使 用 http 配 置 项 ， 包 括 使 用 Nginx 预 设 的 解析 方法 〈 可 以 少 写 
许多 代码 ) 或 者 目 定 义 配 置 项 的 解析 方式 ， 如 果 读 者 对 其 中 较 复 杂 的 配置 块 藤 套头 系 有 锋 
问 ， 在 4.3 市 中 会 从 HTTP 框 架 的 实现 机 制 上 解释 http 配 置 项 的 模型 。 








et 如 何 定位 代码 上 的 问题 是 必须 考虑 的 前 提 条 件 ， 此 时 输出 各 
种 日 志 就 显得 很 关键 了 ，4.4 节 中 会 讨论 Nginx 为 用 户 准 备 好 的 输出 日 志方 法 。 





编写 全 异步 的 HITP 模 块 时 ， 必 须要 有 上 下 文 来 维持 一 个 请 求 的 必要 信息 ， 在 4.5 节 中 ， 
首先 探讨 请 求 的 上 下 文 与 全 异步 实现 的 Nginx 服 务 之 间 的 关系 ， 以 及 如 何 使 用 HTTP 上 下 文 ， 
然后 简单 描述 HTTP 框 架 是 如 何 管理 请 求 的 上 下 文 结构 体 的 。 
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4.1 http 配置 项 的 使 用 场景 





在 第 2 章 中 通过 多 样 化 修改 nginx.conf 文 件 中 的 配置 项 ， 实 现 了 复杂 的 Web 服 务 器 功能 。 
其 中 ，http{...} 内 的 配置 项 最 为 复杂 ， 在 http 配 置 块 内 还 有 server 块 、location 块 等 ， 同 一 个 配 
置 项 可 以 同时 出 现在 多 个 http 块 、server 块 或 location 块 内 。 


那么 ， 如 何 解析 这 样 的 配置 项 呢 ? 在 第 3 章 中 的 mytest 例 子 中 ， 又 是 怎样 获取 nginx.conf 中 
的 配置 的 呢 ? 当 同 一 个 配置 在 http 块 、server 块 、location 块 中 同时 出 现时 ， 应 当选 择 哪 一 个 块 
下 的 配置 呢 ? 当 多 个 不 同 URI 表 达 式 下 的 location 都 配置 了 mytest 这 个 配置 项 ， 然 而 后 面 的 参 
数值 却 不 同时 ，Nginx 是 如 何 处 理 的 呢 ? 这 些 就 是 本 章 将 要 回答 的 问题 。 








我 们 先 来 看 一 个 例子 ， 有 一 个 配置 项 test_str， 它 在 多 个 块 内 都 出 现 了 ， 如 下 所 示 。 


http { 
test str main; 
server { 
listen 80; 
test str server80; 
location UrI7I f 
mytest? 
test str Toc 
} 
location url2 { 
mytest; 
test str loc2; 
} 
} 
server { 
listen 8080; 
test str server8080; 
location /url3 { 
mytest; 
test str loc3; 
} 


在 上 面 的 配置 文件 中 ，test_str 这 个 配置 项 在 http 块 内 出 现 的 值 为 main， 在 监听 80 端 口 的 
server 块 内 test_str 值 为 Server80， 该 server 块 内 有 两 个 location 都 是 由 第 3 章 中 定义 的 mytest 异 块 
处 理 的 ， 而 且 每 个 location 中 又 重新 设置 了 test_str 的 值 ， 分 别 为 locl1 和 lo0c2。 在 这 之 后 义 定义 
了 监听 8080 端 口 的 server 块 ， 并 重 定 义 test_str 的 值 为 server8080， 这 个 server 块 内 定义 的 一 个 
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location 也 是 由 mytest 模 块 处 理 的 ， 而 且 这 个 location 内 再 次 重 定义 了 test_str 的 值 为 loc3。〈 事 
实 上 不 只 是 例子 中 的 server 块 可 以 租 套 location 块 ，location 块 之 间 还 可 以 继续 租 套 ， 这 样 
test_str 的 值 就 更 复杂 了 ， 上 例 中 没有 出 现 location 中 进一步 反复 租 套 location 的 场景 。 在 4.3.3 
节 讨 论 HTTP 框 架 如 何 合 并 配置 项 时 涉及 了 location 块 的 反复 藤 套 问题 ， 请 读者 注意 。) 


在 这 段 很 短 的 配置 中 ，mytest 模 块 将 会 处 理 两 个 监听 端口 上 建立 的 TCP 连 接 ， 以 及 3 种 
HTTP 请 求 ， 请 求 的 URL 分 别 对 应 着 /urll、/url2、/url13。 假 设 mytest 模 块 必 须 取出 test_str 配 置 
项 的 参数 ， 可 是 在 以 上 的 例子 中 test_str 出 现 了 6 个 不 同 的 参数 值 ， 分 别 为 main、server80、 
server8080、1locl1、loc2、loc3， 那 么 在 mytest 模 块 中 我 们 取 到 的 test_str 值 以 哪 一 个 为 准 呢 ? 











事实 上 ，Nginx 的 设计 是 非常 灵活 的 (实际 上 这 是 第 10 章 将 要 介绍 的 HTTP 框 架设 计 
的 ) ， 它 在 每 一 个 htp 块 、server 块 或 1ocation 块 下 ， 都 会 生成 独立 的 数据 结构 来 存放 配置 项 。 
因此 ， 我 们 允许 当 用 户 访问 的 请 求 不 同时 《如 请 求 的 URL 分 别 是 /arll、/marl2、Amrl3) ， 配 置 
项 test_str 可 以 具有 不 同 的 值 。 那 么 ， 当 请 求 是 /url1l 时 ，test_str 的 值 应 当 是 location 抉 下 的 
loc1， 还 是 这 个 location 所 属 的 server 块 下 的 server80， 又 或 者 是 其 所 属 http 块 下 的 值 main 呢 ? 
完全 由 mytest 模 块 自己 决定 ， 我 们 可 以 定义 这 个 行为 。 下 面 在 4.2 节 中 将 说 明 如 何 灵活 地 使 用 
配置 项 ， 在 4.3 节 中 将 探讨 Nginx 实 际 上 是 如 何 实现 http 配 置 功能 的 。 
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4.2 ”怎样 使 用 http 配 置 








事实 上 ， 在 第 3 章 中 己 经 使 用 过 mytest 配 置 项 ， 只 不 过 当时 mytest 配 置 项 是 没有 值 的 ， 只 
是 用 来 标识 当 location 块 内 出 现 mytest 配 置 项 时 就 启用 mytest 模 块 ， 从 而 处 理 匹 配 该 location 表 
达 式 的 用 户 请 求 。 本 章 将 由 易 到 难 来 前 述 HITTP 模 块 是 怎样 获得 感 兴趣 的 配置 项 的 。 





处 理 http 配 置 项 可 以 分 为 下 面 4 个 步骤 : 


1) 创建 数据 结构 用 于 存储 配置 项 对 应 的 参数 。 


— 


2) 设 定 配置 项 在 nginx.conf 中 出 现时 的 限制 条 件 与 回调 方法 。 


实现 第 2 步 中 的 回调 方法 ， 或 者 使 用 Nginx 框 架 预 设 的 14 个 回调 方法 。 


— 


3 


4) 合并 不 同 级 别 的 配置 块 中 出 现 的 同名 配置 项 。 


We 


不 过 ， 这 4 个 步骤 如 何 与 Nginx 有 机 地 结合 起 来 呢 ? 就 是 通过 第 3 章 中 介绍 过 的 两 个 数据 
结构 ngx_http _ module t 和 nsgx_command t， 它 们 都 是 定义 一 个 HTTP 模 块 时 不 可 或 缺 的 部 分 


4.2.1 分 配 用 于 保存 配置 参数 的 数据 结构 


首先 需要 创建 一 个 结构 体 ， 其 中 包含 了 所 有 我 们 感 兴 趣 的 参数 。 为 了 说 明 14 种 预 设 配 置 
项 的 解析 方法 ， 我 们 将 在 这 个 结构 体 中 定义 14 个 成 员 ， 存 储 感 兴趣 的 配置 项 参数 。 例 如 : 





typedef struct { 
ngx str t my_str; 
ngx int t my _ num; 


ngx flag t my_ flag; 
size t my size; 

ngx array t* my_str array; 
ngx array t* my keyval; 
off 起 my_ off; 

ngx msec t my_msec; 
time t my_sec; 

ngx bufs t Ty 


ngx uint t 
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ngx uint 七 my_access; 
ngx path t* my Path 
} ngx http mytest conf 七 








ngx_http_ mytest_conf t 中 的 14 个 成 员 存储 的 配置 项 都 不 相同 ， 读 者 可 暂时 忽略 上 面 
ngx_http_mytest_conf tt 结构 中 一 些 没 见 过 的 Nginx 数 据 结 构 ， 这 些 将 在 4.2.3 节 中 介绍 。 





为 什么 要 这 么 严格 地 用 一 个 结构 体 来 存储 配置 项 的 参数 值 ， 而 不 是 随意 地 定义 几 个 全 局 
变量 来 存储 它们 呢 ? 这 就 要 回 到 4.1 节 中 例子 的 使 用 场景 了 ， 多 个 location 块 (或 者 http 块 、 
server 块 ) 中 的 相同 配置 项 是 允许 同时 生效 的 ， 也 就 是 说 ， 我 们 刚刚 定义 的 
ngx_http_mytest_conf t 结 构 必 须 在 Nginx 的 内 存 中 保存 许多 份 。 事 实 上 ，HTTP 框 架 在 解析 
nginx.conf 文 件 时 只 要 过 到 http{}、server{} 或 者 location{} 配 置 块 就 会 并 刻 分 配 一 个 新 的 
ngx_http_mytest_conf t 结 构 体 。 因 此 ，HTTP 模 块 感 兴趣 的 配置 项 需要 统一 地 使 用 一 个 struct 结 
构 体 来 保存 (否则 HTTP 框 架 无 法 管理 ) ， 如 果 nginx.conf 文 件 中 在 http{} 下 有 多 个 server{} 或 
者 location{}， 那 么 这 个 struct 结 构 体 在 Nginx 进 程 中 就 会 存在 多 份 实例 。 











Nginx 怎 样 管理 我 们 上 自 定 义 的 存储 配置 的 结构 体 ngx http mytest conf t 呢 ? 很 简单 ， 通 过 
第 3 章 中 曾经 提 到 的 ngx http module t 中 的 回调 方法 。 下 面 回顾 一 下 ngx_http module t 的 定 
2 





typedef struct { 

ngx int t (*preconfiguration) (ngx conf 七 cf); 

ngx int t (postconfiguration) (ngx conf 七 cf); 

void (*create main conf) (ngx conf 七 cf); 

char (*init main conf) (ngx conf t cf, void conf); 

void (create srv conf) (ngx conf 七 cf); 

char (*merge srv conf) (ngx conf t cf void prev, void *conf); 

void (create loc conf) (ngx conf 七 cf); 

char (*merge loc conf) (ngx conf 七 cf, void prev, void *conf); 
} ngx http module t; 


)( 
) ( 
) ( 
) ( 





其 中 ，create main conf、create srv conf、create loc_conf 这 3 个 回调 方法 负责 把 我 们 分 
配 的 用 于 保存 配置 项 的 结构 体 传递 给 HTTP 框 架 。 下 面 解 释 一 下 为 什么 不 是 定义 1 个 而 是 定义 
3 个 回调 方法 。 











HTTP 框 架 定义 了 3 个 级 别 的 配置 main、srv、loc， 分 别 表示 直接 出 现在 http{}、 
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server{}、location{} 块 内 的 配置 项 。 当 nginx.conf 中 出 现 http 个 时 ，HTTP 框 架 会 接管 配置 文件 
中 http 介 块 内 的 配置 项 解析 ， 之 后 的 流程 可 以 由 4.3.1 节 中 的 图 4-1 来 了 解 。 当 遇 到 http{...} 配 置 
块 时 ，HTTP 框 架 会 调用 所 有 HTTP 模 块 可 能 实现 的 create_main conf、create_srv_conf、 
create_loc_conf 方 法 生成 存储 main 级 别 配置 参数 的 结构 体 ， 在 遇 到 server{...} 块 时 会 再 次 调用 
所 有 HTTP 模 块 的 create srv conf、create loc conf 回 调 方法 生成 存储 srv 级 别 配置 参数 的 结构 
体 ; 在 遇 到 location{.. 时 则 会 再 次 调用 create loc _ conf 回调 方法 生成 存储 loc 级 别 配置 参数 的 
结构 体 。 因 此 ， 实 现 这 3 个 回调 方法 的 意义 是 不 同 的 ， 例 如 ， 对 于 mytest 模 块 来 说 ， 在 http{} 
块 内 只 会 调用 1 次 create main conf， 而 create loc_conf 可 能 会 被 调用 许多 次 ， 也 就 是 有 许多 个 
由 create loc_conf 生 成 的 结构 体 。 


普通 的 HTTP 模 块 往往 只 实现 create_loc_conf 回 调 方 法 ， 因 为 它们 只 关注 匹配 某 种 URL 的 
请 求 。 我 们 的 mytest 例 和子 也 是 这 样 实现 的 ， 这 里 实现 create_ loc_conf 的 是 
ngx http mytest create loc conf 方 法 ， 如 下 所 示 。 





static void* ngx http mytest create loc conf(ngx conf 七 cf) 


{ 





ngx http mytest conf t mycf; 
mycf = (ngx http mytest conf t *)ngx pcalloc(cf->pool, sizeof (ngx http mytest conf t)); 
if (mycf == NULL) { 

return NULL; 
} 
mycf->my flag = NGX CONF UNSET; 
mycf->my num = NGX CONF UNSET; 
mycf->my str array = NGX CONF UNSET PTR; 
mycf->my keyval = NULL; 
mycf->my off = NGX CONF UN 
mycf->my msec = NGX CONF 了 
mycf->my_sec = NGX CONF_UN 
mycf->my size = NGX CONF U 
return mycf; 




















ET MSEC; 
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EL SILA; 





上 述 代码 中 对 一 些 配置 参数 设置 了 初始 值 ， 这 是 为 了 14 个 预 设 方法 准备 的 ， 下 面 会 解释 
为 什么 要 这 样 赋值 。 


4.2.2” 设 定 配 置 项 的 解析 方式 


下 面 详细 介绍 在 读 取 HTTP 配 置 时 是 如 何 使 用 ngx command tt 结构 的 ， 首 先 回顾 一 下 第 3 
中 THNNNNNNDD tp: 7/ Ww 1 1 nuxprobe. con 








章 中 曾经 提 到 过 的 定义 ， 再 详细 介绍 每 个 成 员 的 意义 。 





struct ngx command S { 
ngx str t name; 
ngx uint t type; 
char (set) (ngx conf t cf, ngx command t cmd, void conf); 
ngx uint t conf; 
ngx uint t offset; 
void post; 





(1) ngx str tname 


其 中 ，name 是 配置 项 名 称 ， 如 4.1 节 例子 中 的 “test_str”。 
(2) ngx uint ttype 


其 中 ，type 决 定 这 个 配置 项 可 以 在 哪些 块 〈( 如 http、server、location、if、upstream 块 等 ) 
中 出 现 ， 以 及 可 以 携带 的 参数 类 型 和 个 数 等 。 表 4-1 列 出 了 设置 http 配 置 项 时 type 可 以 取 的 
值 。 注 意 ，type 可 以 同时 取 表 4-1 中 的 多 个 值 ， 各 值 之 间 用 | 符号 连接 ， 例 如 ，type 可 以 取 值 为 
NGX _ HTTP MAIN CONFINGX HTTP SRV CONFINGX HTTP LOC CONFINGX CONF TAK 





表 4-1 ngx_command_t 结 构 体 中 type 成 员 的 取 值 及 其 意义 
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ype 类 型 意义 

- 般 由 NGX CORE MODULE 类 型 的 核心 模块 使 用 . 
仅 与 下 面 的 NGX_MAIN_CONF 同时 设置 ， 表 示 模 块 需要 
解析 不 属于 任何 人 内 的 全 局 配置 项 。 它 实际 上 会 指定 set 
方法 里 的 第 3 个 参数 conf 的 值 ， 使 之 指向 每 个 模块 解析 全 
局 配置 项 的 配置 结构 体 ” 





处 理 配 辕 项 时 获取 |NGX_DIRECT_CONF 
当前 配置 块 的 方式 


目前 未 使 用 ， 设 置 与 否 均 无 意义 

配置 项 可 以 出 现在 全 局 配置 中 ， 即 不 属于 任何 {} 配置 块 
NGX EVENT CONF 配置 项 可 以 出 现在 events {} 块 内 

NGX MAIL MAIN CONF 配置 项 可 以 出 现存 mail 人 块 或 者 imap {1 块 内 


配置 项 可 以 出 现在 server {} 块 内 ， 然 而 该 server 他 块 必 
须 属于 mail 2 块 或 者 imap 人 块 
NGX HTTP MAIN_CONF 配置 项 可 以 出 规 在 http 如 块 内 

配置 项 可 以 出 现在 server {} 块 内 ， 然 而 该 server 块 必须 
属于 http 全 块 


NGX MAIL SRV_CONEF 


NGX HTTP_ SRV_CONF 


配 图 项 可 以 在 哪些 配置 项 可 以 出 现在 location 人 块 内 ， 然 而 该 location 块 
和 配置 块 中 出 现 NGX_HTTP LOC CONF 必须 属于 http {} 块 


配置 项 可 以 出 现在 upstream f} 块 内 然而 该 upstream 块 
必须 属于 http 人 块 

配置 项 可 以 出 现在 server 抉 内 的 让 和 仔 块 中 。 目 前 仅 有 
rewrite 模块 会 合用， 该 诺 块 必须 属于 http f} 块 

配置 项 可 以 出 现在 location 抉 内 的 让 时 块 中 。 目前 公有 
rewrite 模块 会 使 用 .该 让 抉 必须 属于 http {} 块 

配置 项 可 以 出 现在 limit except 人 块 内 ， 然 而 该 limit 
except 块 必须 属于 http 们 抉 


NGX_HTTP_UPS_CONF 


NGX_ HTTP SIF_CONF 





NGX_ HTTP_LIF_CONF 


NGX HTTP LMT_ CONF 


NGX CONF NOARGS 配置 项 不 携带 任何 参数 
NGX CONF TAKEI 配置 项 必须 携带 1 个 参数 
NGX CONF TAKE2 配置 项 必须 携带 2 个 参数 
NGX CONF _ TAKE3 配置 项 必须 携带 3 个 参数 
NGX_CONF TAKE4 配置 项 必须 携带 4 个 参数 
i NGX CONF TAKES 配置 项 必须 携带 5 个 参数 
个 数 INGX CONF TAKE6 配置 项 必须 携带 6 个 参数 


NGX_CONF_TAKE7 配置 项 必须 携带 7 个 参数 

NGX CONF_ TAKE12 配置 项 可 以 携带 1 个 参数 或 2 个 参数 
NGX CONF_ TAKE13 配置 项 可 以 携带 1 个 参数 或 3 个 参数 
NGX CONF TAKE23 配置 项 可 以 携带 2 个 参数 或 3 个 参数 
NGX CONF TAKE123 配置 项 可 以 携带 1 ~ 3 个 参数 

NGX CONF TAKE1234 配置 项 可 以 携带 1 ~ 4 个 参数 
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type 类 型 type 取 值 意 义 


NGX CONF ARGS NUMBER 目前 未 使 用 ， 无 意义 





配置 项 定义 了 一 种 新 的 和合 块 。 例 如 ，http、server、 
NGX CONF BLOCK location 等 配置 ， 它 们 的 type 都 必须 定义 为 NGX_CONF_ 
BLOCK 


NGX CONF ANY 不 验证 配置 项 携 市 的 参数 个 数 


配置 项 携带 的 参数 只 能 是 1 个， 并 且 参 数 的 值 只 能 是 on 


或 者 off 


NGX CONF 1MORE 配置 项 携带 的 参数 个 数 必须 超过 1 个 
| NGX _ CONF 2MORE 配置 项 携带 的 参数 个 数 必须 超过 2 个 
限制 配置 项 后 的 参 


数 出 现 的 形式 表示 当前 配置 项 可 以 出 现在 任意 块 中 (包括 不 属于 任何 
块 的 全 局 配置 )， 它 仅 用 于 配合 其 他 配置 项 使 用 。type 中 未 
加 NGX_CONF MULII 时 ， 如 果 一 个 配置 项 出 现在 type 
成 员 未 标明 的 配置 块 中 ,那么 Nginx 会 认为 该 配置 项 非法 ， 
最 后 将 导致 Nginx 启动 失败 。 但 如 果 type 中 加 入 了 NGX 
NGX CONF MULTI CONF_MULTI， 则 认为 该 配置 项 一 定 是 合法 的 ， 然 而 又 
会 有 了 两 种 不 同 的 结果 : 山 如 果 配 置 项 出 现在 type 指示 的 块 
中 ， 则 会 调用 set 方法 解析 配置 项 ; 避 如 果 配 置 项 没有 出 现 
在 type 指示 的 块 中 ， 则 不 对 该 配置 项 做 任何 处 理 。 因 此 ， 
NGX_CONF_MULTI 会 使 得 配置 项 出 现在 未 知 块 中 时 不 会 
出 错 。 目前， 还 没有 官方 模块 使 用 过 NGX_CONF MULTI 





NGX CONF FLAG 





每 个 进程 中 都 有 一 个 唯一 的 ngx_cycle_t 核 心 结 构 体 ， 它 有 一 个 成 员 conf_ctx 维 护 着 所 有 
模块 的 配置 结构 体 ， 其 类 型 是 void****。conf_ctx 意 义 为 首先 指向 一 个 成 员 避 为 指针 的 数组 ， 
其 中 每 个 成 员 指 针 又 指向 另外 一 个 成 员 必 为 指针 的 数组 ， 第 2 个 子 数 组 中 的 成 员 指 针 才 会 指 
向 各 模块 生成 的 配置 结构 体 。 这 正 是 为 了 事件 模块 、http 模 块 、mail 模 块 而 设计 的 ， 第 9、10 
章 都 有 详 述 ， 这 有 利于 不 同 于 NGX_CORE_MODUIE 类 型 的 特定 模块 解析 配置 项 。 然 而 ， 
NGX_CORE MODULE 类 型 的 核心 模块 解析 配置 项 时 ， 配 置 项 一 定 是 全 局 的 ， 不 会 从 属于 
任何 全 配置 块 的 ， 它 不 需要 上 述 这 种 双 数 组 设计 。 解 析 标 识 为 NGX_DIRECT_ CONF 类 型 的 
配置 项 时 ， 会 把 void**** 类 型 的 conf_ctx 强 制 转换 为 void**， 也 就 是 说 ， 此 时 ， 在 conf_ctx 指 向 
的 指针 数组 中 ， 每 个 成 员 指 针 不 再 指向 其 他 数组 ， 直 接 指向 核心 模块 生成 的 配置 结构 体 。 因 
此 ，NGX_DIRECT_CONF 仅 由 NGX_CORE_MODULE 类 型 的 核心 模块 使 用 ， 而且 配置 项 只 


应 该 出 现在 全 
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@ 注意 ”如 果 HTTP 模 块 中 定义 的 配置 项 在 nginx.conf 配 置 文件 中 实际 出 现 的 位 置 和 参 
数 格式 与 type 的 意义 不 符 ， 那 么 Nginx 在 启动 时 会 报错 。 


(3) char(set)(ngx conf t*cfingx command t*cmd,void*conf) 





关于 set 回 调 方 法 ， 在 第 3 章 中 处理 mytest 配 置 项 时 已 经 使 用 过 ， 其 中 mytest 配 置 项 是 不 带 
参数 的 。 如 果 处 理 配置 项 ， 我 们 既 可 以 自己 实现 一 个 回调 方法 来 处 理 配置 项 (4.2.4 节 中 会 举 
例 说 明 如 何 自 定义 回调 方法 ) ， 也 可 以 使 用 Nginx 预 设 的 14 个 解析 配置 项 方法 ， 这 会 少 写 许 
多 代码 ， 表 4-2 列 出 了 这 些 预 设 的 解析 配置 项 方法 。 我 们 将 在 4.2.3 节 中 举例 说 明 这 些 预 设 方 
法 的 使 用 方式 。 





表 4-2 预 设 的 14 个 配置 项 解析 方法 
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预 设 方法 名 


nex_ conf set flag slot 


nex conf set str slot 


ngx_ conf set str array slot 


ngx_ conf set keyval Slot 


nex conf set num Slot 


ngx conf set Size Slot 


ngx cont set off slot 


ngx_conf set msee slot 


ngx_conf set Sec slot 


ngx conf set bufs slot 


行 为 

如 果 nginx.conf 文件 中 某 个 配置 项 的 参数 是 on 或 者 off ( 即 希 望 配 置 项 表达 打 
开 或 考 关 闭 革 个 功能 的 意思 )， 而 且 在 Nginx 模块 的 代码 中 使 用 ngx_flag 上 变量 来 
保存 这 个 配置 项 的 参数 ， 就 可 以 将 set 回调 方法 设 为 ngx_conf set flag slot。 当 
nginx.conf 文件 中 敌 数 是 on 时， 代码 中 的 ngx_flag 1 类 型 变量 将 设 为 1， 参数 为 
o 作 时 则 设 为 0 

如 果 配 置 项 后 只 有 1 个 参数 . 同时 在 代码 中 我 们 希望 用 ngx_str t+ 类 地 的 变量 来 
保存 这 个 配置 项 的 参数 ， 则 可 以 合用 ngx_conf set_str_slot 方法 

如 果 这 个 配置 项 会 出 现 多 次 ， 每 个 配 轩 项 后 面 都 跟着 1 个 参数 ， 而 在 程序 中 我 
们 希望 仪 用 一 个 ngx_array 1 动态 数组 (用 法 见 7.3 节 ) 来 存储 所 有 的 参数 ， 且 数 
组 中 的 每 个 参数 都 以 ngx_str 1 来 存储 .那么 预 设 的 ngx_conf set str array_ slot 方 
法 可 以 帮 我 们 做 到 

与 ngx_conf set_str_array_slot 类似 ， 也 是 用 一 个 ngx_array t 数组 来 存储 所 有 
同名 配置 项 的 参数 。 只 是 每 个 配置 项 的 参数 不 再 只 是 1 个 ， 而 必须 是 两 个 ， 且 以 
"配置 项 名 关键 字 值 ;” 的 形式 出 现在 nginx.conf 文件 中 ， 同 时 ，ngx_conf set_ 
keyval_slat 将 把 这 些 配置 项 转化 为 数组 ， 基 中 每 个 元 素 都 存储 着 key/value 键 值 对 

配置 项 后 必须 揽 带 1 个 人 参数， 且 只 能 是 数字 。 存 储 这 个 参数 的 变量 必须 是 束 型 

配置 项 后 必须 携带 1 个 参数， 表示 空间 大 小 ， 可 以 是 一 个 数字 ， 这 时 表示 字 节 
数 (Byte)。 如 有 果 数 字 后 跟着 k 或 者 人 民 ， 就 表示 Kilobyte，1KB=1024B ; 如 果 数 字 
后 跟着 m 或 者 M， 就 表示 Megabyte、1MB=1024KB。ngx_conf set size slot 解析 
后 将 把 配置 项 后 的 参数 转化 成 以 字 节 数 为 单位 的 数字 

配置 项 后 必须 携带 1 个 参数 ， 表 示 室 间 上 的 偏 移 最 。 它 与 设置 的 参数 非常 类 似 ， 
其 和 参数 是 一 个 数字 时 表示 Byte， 也 可 以 在 后 面 加 单位 .但 与 ngx_conf set size 
slot 不 同 的 是 ,数字 后 面 的 单位 不 仅 可 以 是 k 或 者 K、m 或 者 M， 还 可 以 是 g 或 
者 G， 这 时 表示 Gigabyte，1GB=1024MB。ngx _conf set_off slot 解析 后 将 把 配置 
项 后 的 参数 转化 成 以 字 节 数 为 单位 的 数字 

配置 项 后 必须 携带 1 个 人 参数， 表示 时 间 。 这 个 参数 可 以 在 数字 后 面 加 单位 ， 如 
果 单 位 为 s 或 者 没有 任何 单位 ,那么 这 个 数字 表示 秒 ; 如 果 单 位 为 m， 则 表示 
分 钟 ，1m=60s ; 妇 旭 单位 为 hb. 则 表示 小 时 ，1h=60m ; 如 时 单位 为 d， 则 表示 
天 .1d=24h ; 如 果 单 位 为 w， 则 表示 周 ，1w=7d ; 如 果 单 位 为 M， 则 表示 月 ， 
IM=30d ; 如果 单位 为 y， 则 表示 年 ，1y=365d。ngx_conf set_msec_slot 解析 后 将 
把 配置 项 后 的 参数 转化 成 以 毫秒 为 单位 的 数字 

与 ngx_conf set_msec_slot 非常 类 似 ， 叭 一 的 区 别 是 ngx_conf set_ msec _ slot 解 
本 后 将 把 配置 项 后 的 参数 转化 成 以 毫秒 为 单位 的 数字 ， 而 ngx_conf set sec_ slot 
解析 后 会 把 配置 项 后 的 参数 转化 成 以 秒 为 单位 的 数字 

配置 项 后 必须 携带 一 两 个 参数 ,第 1 个 参数 是 数字 ， 第 2 个 参数 表示 空间 大 小 。 
例如 ， ”gzip_buffers 4 8k;”( 通 常用 来 表示 有 多 少 个 ngx_buf t 缓冲 区 )， 共 中 第 1 
个 参数 不 可 以 携带 任何 单位， 第 2 个 参数 不 带 任何 单位 时 表示 Byte， 如 果 以 k 或 
者 作为 单位 ， 则 表示 Kilobyte， 如 果 以 m 或 者 M 作为 单位 ， 则 表示 Megabyte。 
ngx_conf set_bufs slot 解析 后 会 把 配置 项 后 的 两 个 参数 转化 成 ngx_bufs t+ 结构 体 
下 的 两 个 成 员 。 这 个 配置 项 对 应 于 Nginx 最 喜欢 用 的 多 缓冲 区 的 解决 方案 ( 如 接 
收 连 接 对 端 发 来 的 TCP 流 ) 
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预 设 方法 名 行 为 
配置 项 后 必须 携带 1 个 参数 ， 其 取 值 范围 必须 是 我 们 设 定 好 的 池 件 串 之 一 (就 
像 C 语言 中 的 枚 举 一 样 )。 首 先 ， 我 们 要 用 ngx_conf_enum t 结构 定义 配置 项 的 取 
值 范围 ， 并 设 定 每 个 值 对 应 的 序列 号 。 然 后 ，ngx_conf _set_enum_slot 将 会 把 配置 
项 参数 转化 为 对 应 的 序列 号 
与 ngx_conf set bitmask slot 类 似 ， 配 置 项 后 必须 携带 1 个 参数 ， 其 取 值 范围 必 
| 须 是 设 定好 的 字符 串 之 一 。 首 先 ， 我 们 要 Sd t 结 构 定 义 配置 项 
ngx conf set bitmask slot , Ee Se eo Ne 
的 取 值 范围 ， 并 设 定 每 个 值 对 应 的 比特 位 。 注意 ， 每 个 值 所 对 应 的 比特 位 都 要 不 
同 。 然 后 ngx_conf set bitmask slot 将 会 把 配置 项 参数 转化 为 对 应 的 比特 位 
文 个 方法 用 于 设置 目录 或 者 文件 的 读 写 权限 。 配 置 项 后 可 以 携带 1 ~ 3 个 参数 ， 
可 以 是 如 下 形式 : user:rw group:rw allrw。 注 意 ， 它 的 意义 与 Linux 上 文件 或 者 


ngx conf set enum _ slot 








ngx_cont set access_slot 目录 的 权限 意义 是 一 致 的 ,但 是 user/group/all 后 面 的 权限 只 可 以 设 为 rw ( 读 / 写 ) 
或 者 1 (只 读 ), 不 可 以 有 er 任何 形式 ， 如 Ww 或 者 IX 等 。ngx_conf set_access 
slot 2 会 把 这 些 参数 转化 为 一 个 整 型 


个 方法 用 于 设置 路 径 ， 配 置 项 后 必须 携带 1 个 参数 ,表示 1 个 有 意义 的 路 径 


ngx conf set path slot hy Pa 
人 _path_slot 将 参数 转化 为 ngx_path t 结构 





(4) ngx uint tconf 


conf 用 于 指示 配置 项 所 处 内 存 的 相对 偏 移 位 置 ， 仅 在 type 中 没有 设置 
NGX_DIRECT_CONF 和 NGX_MAIN_CONF 时 才 会 生效 。 对 于 HTTP 模 块 ，conf 是 必须 要 设置 
的 ， 它 的 取 值 范围 见 表 4-3。 


表 4-3 npgx_command ft 结 构 中 的 conf 成 员 在 HTTP 模 块 中 的 取 值 及 其 意 


conf 在 HTTP 模块 中 的 取 值 意 义 
NGX HTTP MAIN CONF OFFSET 使 用 create_main_conf 方 法 产生 的 结构 体 来 存储 解析 出 的 配置 项 参数 
NGX _ HTTP SRV CONF OFFSET 使 用 create_srv_conf 方法 产生 的 结构 体 来 存储 解析 出 的 配置 项 参数 
NGX HTTP LOC CONF OFFSET 使 用 create_loc_conf 方 法 产生 的 结构 体 来 存储 解析 出 的 配置 项 参数 





为 什么 HITP 模 块 一 定 要 设置 conf 的 值 呢 ? 因为 HTTP 框 架 可 以 使 用 预 设 的 14 种 方法 自动 
地 将 解析 出 的 配置 项 写 入 HTTP 模 块 代码 定义 的 结构 体 中 ， 但 HTTP 模 块 中 可 能 会 定义 3 个 结 
构 体 ， 分 别 用 于 存储 main、srv、loc 级 别 的 配置 项 (对 应 于 create_main_conf、 
create_STV_conf、create_ loc_conf 方 法 创建 的 结构 体 ) ， 而 HTTP 框架 自动 解析 时 需要 知道 应 把 


解析 出 的 配置 项 值 写 入 哪个 结构 体 中 ， 这 将 由 conf 成 员 完成 。 
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因此 ， 对 conf 的 设置 是 与 ngx http module t 实 现 的 回调 方法 〈 在 4.2.1 节 中 介绍 ) 相关 的 。 
如 果 用 于 存储 这 个 配置 项 的 数据 结构 是 由 create_ main conf 回调 方法 完成 的 ， 那 么 必须 把 conf 
设置 为 NGX_HTTP MAIN_CONF OFFSET。 同 样 ， 如 果 这 个 配置 项 所 属 的 数据 结构 是 由 
create_SrvV_conf 回 调 方法 完成 的 ， 那 么 必须 把 conf 设 置 为 NGX _ HTTP SRV_CONF OFFSET。 
可 如 果 create loc_conf 负 责 生成 存储 这 个 配置 项 的 数据 结构 ， 就 得 将 conf 设 置 为 
NGX _ HTTP LOC CONF_ OFFSET。 





目前 ， 功 能 较为 简单 的 HTTP 模块 都 只 实现 了 create loc_conf 回 调 方法 ， 对 于 http 位、 
server 冉 块 内 出 现 的 同名 配置 项 ， 都 是 并 入 某 个 location{} 内 create_ loc_conf 方 法 产生 的 结构 体 
中 的 (在 4.2.5 节 中 会 详 述 如 何 合并 配置 项 ) 。 当 我 们 希望 同时 出 现在 http{}、server{}、 
location{} 块 的 同名 配置 项 ， 在 HTTP 模 块 的 代码 中 保存 于 不 同 的 变量 中 时 ， 就 需要 实现 
create_main conf 方 法 、create_Srv_conf 方 法 产生 新 的 结构 体 ， 从 而 以 不 同 的 结构 体 独立 保存 
不 同 级 别 的 配置 项 ， 而 不 是 全 部 合并 到 某 个 location 下 create loc_conf 方 法 生成 的 结构 体 中 。 





($5) ngx uint t offset 





ofget 表 示 当 前 配置 项 在 整个 存储 配置 项 的 结构 体 中 的 偶 移 位 置 《以 字 节 〈Byte) 为 单 
位 ) 。 举 个 例子 ， 在 32 位 机 器 上 ，int《〈 整 型 ) 类 型 长 度 是 4 字 节 ， 那 么 看 下 面 这 个 数据 结 
构 : 


typedef struct { 
int a; 
int b; 
Tnt 

} test stru; 








如 果 要 处 理 的 配置 项 是 由 成 员 b 来 存储 参数 的 ， 那 么 这 时 b 相 对 于 test_stru 的 侦 移 量 就 是 
4; 如 有 林 要 处 理 的 配置 项 由 成 员 c 来 存储 参数 ， 那 么 这 时 c 相 对 于 test_stru 的 偶 移 量 就 是 8。 








实际 上 ， 这 种 计算 工作 不 用 用 户 上 自己 来 做 ， 使 用 offsetof 宏 即 可 实现 。 例 如 ， 在 上 例 中 取 
b 的 偏 移 量 时 可 以 这 么 做 : 
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offsetof (test stru, b) 








其 中 ，offsetof 中 第 1 个 参数 是 存储 配置 项 的 结构 体 名 称 ， 第 2 个 参数 是 这 个 结构 体 中 的 变 
量 名 称 。offsetof 尾 会 返回 这 个 变量 相对 于 结构 体 的 偏 移 量 。 


全 提示 。 offsetof 这 个 宏 是 如 何 取得 成 员 相对 结构 体 的 偏 移 量 的 呢 ?” 其 实 很 简单 ， 它 的 
实现 类 似 于 : #define offsetofttypememben) (size_&(((typen)0)->member)。 可 以 看 到 ，offsetof 将 0 
地 址 转换 成 type 结 构 体 类 型 的 指针 ， 并 在 访问 member 成 员 时 取得 member 成 员 的 指针 ， 这 个 指 
针 相 对 于 0 地 址 来 说 自然 就 是 成 员 相 对 于 结构 体 的 偏 移 量 了 。 


设置 offset 有 什么 作用 呢 ? 如果 使 用 Nginx 预 设 的 解析 配置 项 方法 ， 就 必须 设置 offset， 这 
样 Nginx 首 先 通 过 conf 成 员 找 到 应 该 用 哪个 结构 体 来 存放 ， 然 后 通过 offset 成 员 找到 这 个 结构 
体 中 的 相应 成 员 ， 以 便 存放 该 配置 。 如 果 是 自 定义 的 专用 配置 项 解析 方法 (只 解析 某 一 个 配 
置 项 ) ， 则 可 以 不 设置 offset 的 值 。 读 者 可 以 通过 4.3.4 节 来 了 解 预 设 配 置 项 解析 方法 是 如 何 
使 用 offset 的 。 





(6) void*post 
post 指 针 有 许多 用 途 ， 从 它 被 设计 成 void* 束 可 以 看 出 。 


如 果 目 定义 了 配置 项 的 回调 方法 ， 那 么 post 指 针 的 用 途 完 全 由 用 户 来 定义 。 如 果 不 使 用 
它 ， 那 么 随意 设 为 NULL 即 可 。 如 果 想 将 一 些 数据 结构 或 者 方法 的 指针 传 过 来 ， 那 么 使 用 post 
也 可 以 。 








如 果 使 用 Nginx 预 设 的 配置 项 解析 方法 ， 就 需要 根据 这 些 了 预 设 方法 来 决定 post 的 使 用 方 
式 。 表 4-4 说 明了 post 相 对 于 14 个 预 设 方法 的 用 途 。 


表 4-4 negx_command_t 结 构 中 post 的 取 值 及 其 意义 
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post 的 使 用 方式 


可 以 选择 是 否 实 现 。 如 果 设 为 NULL， 则 表示 不 实现 ， 和 否则 必须 实现 为 指向 
ngx_conf post t 结构 的 指针 。ngx_ conf_post_ t 中 包含 一 个 方法 指针 ， 表 示 在 解析 
当前 配置 项 完毕 后 ， 需要 回调 这 人 1 ~、 方 祷 


指 问 ngx_conf enum t 数 组 ， 表 示 当 前 配置 项 的 参数 必须 设置 为 ngx_conf_ 
enum t 规定 的 值 (类 似 枚 举 )。 注 意 ， 使 用 ngx_conf set_enum slot 时 必须 设置 定 
臣 王 淮 a a 数组 ， 并 将 post 成 员 指 癌 该 数组 

指 问 ngx_conf bitmask t 数组， 表示 当前 配置 项 的 参数 必须 设置 为 ngx_conf_ 
bitmask t 规定 的 值 (类 似 枚 举 )。 注 意 ， 使 用 ngx_conf set_bitmask _ slot 时 必须 设 


置 定 义 1 个 ngx_conf bitmask t 数 组， 并 将 post 成 员 指 回 该 数组 


无 任何 用 处 


适用 的 预 设 配 置 项 解析 方法 


ngx conf set flag slot 

ngx conf set str slot 

ngx conf set str array_slot 
ngx conf set keyval slot 


ngx conf set num slot 





ngx conf set size slot 


ngx conf set off slot 





ngx conf set msec slot 


ngx conf set sec slot 


ngx conf set enum slot 


ngx conf set bitmask slot 


ngx conf set bufs slot 
ngx conf set path slot 


ngx conf set access slot 


可 以 看 到 ， 有 9 个 预 设 方法 在 使 用 时 post 是 可 以 设置 为 ngx_conf post t 结 构 体 来 使 用 的 ， 


先 来 看 看 ngx conf post t 的 定义 。 





typedef char (ngx conf post handler pt) (ngx conf 七 cf, 
void data, void *conf); 

typedef struct { 
ngx conf post handler pt post handler; 

} ngx conf post t; 








如 果 需 要 在 解析 完 配 置 项 〈 表 4-4 中 列 出 的 前 9 个 预 设 方法 ) 后 回调 某 个 方法 ， 就 要 实现 
上 面 的 ngx conf post handler pt， 并 将 包含 post_handler 的 ngx conf post t 结 构 体 传 给 post 指 


3 


目前 ，ngx_conf post t 结 构 体 提供 的 这 个 功能 没有 官方 Nginx 模 块 使 用 ， 因 为 它 限制 过 多 
且 post 成 员 过 于 灵活 ， 一 般 完 全 可 以 init main conf 这 样 的 方法 统一 处 理解 析 完 的 配置 项 。 


4.2.3 ”使 用 14 种 预 设 方法 解析 配置 项 
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本 节 将 以 举例 的 方式 说 明 如 何 使 用 这 14 种 Nginx 的 预 设 配置 项 解析 方法 来 处 理 我 们 感 兴 
趣 的 配置 项 。 下 面 仍然 以 4.2.1 节 生成 的 配置 项 结构 体 ngx_http_mytest_conf { 为 例 进 行 说 明 ， 
其 中 会 尽量 把 type 成 员 的 多 种 用 法 部 涵盖 到 。 





(1) ngx conf set flag slot 
假设 我 们 希望 在 nginx.conf 中 有 一 个 配置 项 的 名 称 为 test_flag， 它 的 后 面 携 和 市 1 个 参数 ， 这 


个 参数 的 取 值 必须 是 on 或 者 off。 我 们 将 用 4.2.1 节 中 生成 的 ngx http_mytest_conf t 结 构 体 中 的 
以 下 成 员 来 保存 : 





ngx flag t my flag; 





先 看 一 下 ngx flag t 的 定义 : 





typedef intptr t ngx flag t; 





可 见 ，ngx flag t 与 ngx int t 整 型 是 相当 的 。 可 以 如 下 设置 ngx conf set flag slot 来 帮助 解 
析 test _ flag 参数。 





static ngx command t ngx http mytest commands[] = { 





{ ngx string("test flag"), 

NGX HTTP LOC CONF| NGX CONF FLAG, 

ngx conf set flag slot, 

NGX HTTP LOC CONF OFFSET, 

offsetof (ngx http mytest conf t, my flag), 
NULL }, 
ngx_ null command 


























上 上 段 代 码 表示 ，test_flag 配 置 只 能 出 现在 location{...} 块 中 (更 多 的 type 设 置 可 参见 表 4- 
1) 。 其 中 ，test_flag 配 置 项 的 参数 为 on 时 ，ngx_http_mytest_conf t 结 构 体 中 的 my_flag 会 设 为 
1， 而 参数 为 off 和 时 my flag 会 设 为 0。 
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@ 注意 在 nex_http_mytest_create_loc_conf 创 建 结构 体 时 ， 如 果 想 使 用 
negx_conf _set_flag_slot， 必 须 把 my_flag 初 始 化 为 NGX_CONF_UNSET 宏 ， 也 就 是 4.2.1 节 中 的 语 
和 句 “mycf->test_flag=NGX_CONF_UNSET;” ， 否 则 ngx_conhf _set_flag_ slot 方法 在 解析 时 会 


报 “is duplicate ”错误 。 
(2) ngx conf set str Slot 


假设 我 们 和 希望 在 nginx.conf 中 有 一 个 配置 项 的 名 称 为 test str， 其 后 的 参数 只 能 是 1 个 ， 我 
们 将 用 ngx http mytest_conf t 结 构 体 中 的 以 下 成 员 来 保存 它 。 








ngx str 七 my_str; 





可 以 这 么 设置 ngx conf set str slot 来 实现 test_str 的 解析 ， 如 下 所 示 。 





static ngx command t ngx http mytest commands[] = { 





{ ngx string("test str"), 
NGX HTTP MAIN CONF|INGX HTTP SRV CONF|NGX HTTP LOC CONF| NGX CONF TAKE1， 
ngx conf set str slot, 
NGX HTTP LOC CONE OFFSET, 
offsetof (ngx http mytest conf t, my str), 
NULL }, 
ngx null command 

















}; 





以 上 代码 表示 test_str 可 以 出 现在 http{...}、server{...} 或 者 location{...} 块 内 ， 它 携带 的 1 个 
参数 会 保存 在 my_str 中 。 例 如 ， 有 以 下 配置 : 





location ……: 


{ 
test str apple; 
} 





那么 ，my_str 的 值 为 {len=5;data="“apple”;}。 
(3) ngx conf set str array slot 
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如 果 和 希望 在 nginx.conf 中 有 多 个 同名 配置 项 ， 如 名 称 是 test_str array， 那 么 每 个 配置 项 后 
都 跟着 一 个 字符 串 参数 。 这 些 同名 配置 项 可 能 具有 多 个 不 同 的 参数 值 。 这 时 ， 可 以 使 用 
ngx_conf set_str array_slot 预 设 方法 ， 它 将 会 把 所 有 的 参数 值 都 以 ngx_str t 的 类 型 放 到 
ngx_array t 队 列 容器 中 ， 如 下 所 示 。 





static ngx command t ngx http mytest commands[] = { 





{ ngx string("test str array"), 
NGX HTTP LOC CONF | NGX CONF TAKE1, 
ngx conf set str array slot, 
NGX HTTP LOC CONE OFFSET, 
offsetof (ngx http mytest conf t, my str array), 
NULL }, 
ngx null command 


my 


























}; 





在 4.2.1 节 中 已 看 到 my _str array 是 ngx array 从 类 型 的 。ngx array 人 饮 - 据 结构 的 使 用 方法 与 
ngx_list_t 类 似 。 本 间 不 详细 讨论 ngx array t 答 器 ， 感 兴趣 的 读者 可 以 直接 阅读 第 6 章 人 查看 
ngx_array t 的 使 用 特点 。 


上 面 代码 中 的 test_str array 配 置 项 也 只 能 出 现在 location{...} 块 内 。 如 果 有 以 下 配置 : 





loOcation * 


{ 
test str array Content-Length; 
test str array Content-Encoding; 





} 











那么 ，my_str_array->nelts 的 值 将 是 2， 表 示 出 现 了 两 个 test_str_array 配 置 项 。 而 且 ， 
my_str_array->elts 指 向 ngx_str_t 类 型 组 成 的 数组 ， 这 样 就 可 以 按 以 下 方式 访问 这 两 个 值 。 





ngx_ str t*pstr=mycf->my str array->elts; 





于 是 ，pstr[0] 和 pstr[1] 可 以 取 到 参数 值 ， 分 别 是 {len=14;data=“Content-Length”;} 和 
{len=16;data=“Content-Encoding”;} 。 从 这 里 可 以 看 到 ， 当 处 理 HTTP 涉 部 这 样 的 配置 项 时 是 很 
适合 使 用 ngx conf set str array slot 预 设 方法 的 。 
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(4) ngx conf set keyval slot 


ngx conf set keyval slot 与 ngx conf set str array slot 非 常 相似 ， 唯 一 的 不 同 点 是 
ngx conf set str array slot 要 求 同 名 配置 项 后 的 参数 个 数 是 1， 而 ngx conf set keyval slot 则 要 
求 配置 项 后 的 参数 个 数 是 2， 分 别 表示 keyvalue。 如 果 用 ngx array 人 类 型 的 my keyval 变 量 存 
储 以 test_ keyval 作 为 配置 名 的 参数 ， 则 必须 设置 NGX_CONF _TAKE2， 表 示 test_ keyval 后 跟 两 
个 参数 。 例 如 : 





static ngx command t ngx http mytest commands[] = { 





{ ngx string("test keyval"), 
NGX_ HTTP LOC CONF | NGX CONF TAKE2, 
ngx conf set keyval silot, 
NGX HTTP LOC CONE OFFSET, 
offsetof (ngx http mytest conf t, my keyval), 
NULL }, 
ngx null command 


























}; 





如 果 nginx.conf 中 出 现 以 下 配置 项 : 





location = 


{ 
test keyval Content-Type image/png; 
test keyval Content-Type image/gif; 
test keyval Accept-Encoding gzip; 














} 








那么 ，ngx_array 从 类 型 的 my_keyval 将 会 有 3 个 成 员 ， 每 个 成 员 的 类 型 如 下 所 示 。 





typedef struct { 
ngx_ str 七 key; 
ngx str 七 value; 
} ngx keyval t; 








因此 ， 通 过 授 历 my_keyval 束 可 以 获取 3 个 成 员 ， 分 别 是 {“Content-Type”,“image/png”}、 
{“Content-Type”,“image/gif”; 、{“Accept-Encodineg”“gzip”} 。 例 如 ， 取 得 第 1 个 成 员 的 代码 如 
下 





PTT TT http: // ww inuxprobe. con 








ngx log error (NGX LOG ALERT, r->connection->log, 0, 
"my _ keyval key=%*s,value=%$*s,", 
DPKkV[0] .key.len,pkv[0] .key.data, 
pkv[0] .value.len,pkv[0] .value.data); 





对 于 ngx_log error 日 志 的 用 法 ， 将 会 在 4.4 节 详细 说 明 。 


@ 注意 在 nex_http_mytest_create_loc_conf 创 建 结构 体 时 ， 如 果 想 使 用 
ngx_conf set_keyval_slot， 必 须 把 my_keyval 初 始 化 为 NULL 空 指针 ， 也 就 是 4.2.1 节 中 的 语 


名 “mycf->my_keyval=NULIL;”， 否 则 ngx_conf set_ keyval_slot 在 解析 时 会 报错 。 
($5) ngx conf set num slot 


ngx_conf set_num slot 处 理 的 配置 项 必须 携带 1 个 参数 ， 这 个 参数 必须 是 数字 。 我 们 用 
ngx_http_mytest_conf tt 结构 中 的 以 下 成 员 来 存储 这 个 数字 参数 如 下 所 示 。 





ngx int 七 my num; 





如 果 用 "test_ num" 表 示 这 个 配置 项 名 称 ， 那 么 ngx_command t 可 以 写成 如 下 形式 。 





static ngx command t ngx http mytest commands[] = { 





{ ngx string("test num"), 
NGX_ HTTP LOC CONF | NGX CONF TAKE1， 
ngx conf set num slot, 
NGX HTTP LOC CONE OFFSET, 
offsetof (ngx http mytest conf t, my num), 
NULL }, 

ngx null command 


}; 





























如 果 在 nginx.conf 中 有 test num 10; 配 置 项 ， 那 么 my _ num 变量 就 会 设置 为 10。 


@ 注意 ”在 ngx_http_mytest_create_loc_conf 创 建 结构 体 时 ， 如 果 想 使 用 
ngx_conf_set_num_slot， 必 须 把 my_num 初 始 化 为 NGX_CONF_UNSET 宏 ， 也 就 是 4.2.1 节 中 的 
语句 “mycf->my_num 二 NGX_CONF_UNSET;”， 和 否则 ngx_conf_set_num_slot 在 解析 时 会 报 
错 。 
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(6) ngx conf set size Slot 


如 果 希 望 配置 项 表达 的 售 义 是 空间 大 小 ， 那 么 用 ngx_conf set_size_slot 来 解析 配置 项 是 非 
常 合适 的 ， 因 为 ngx_conf set_size_slot 允 许配 置 项 的 参数 后 有 单位 ， 例 如 ，k 或 者 K 表 示 
Kilobyte，m 或 者 M 表 示 Megabyte。 用 ngx http mytest_conf tt 结构 中 的 size tmy size; 来 存储 参 
数 ， 解 析 后 的 my_size 表 示 的 单位 是 字 节 。 例 如 : 





static ngx command t ngx http mytest commands[] = { 





{ ngx string("test size"), 
NGX_ HTTP LOC CONF | NGX CONF TAKE1， 
ngx conf set size slot, 
NGX HTTP LOC CONE OFFSET, 
offsetof (ngx http mytest conf t, my size), 
NULL }, 
ngx null command 


}; 





























如 果 在 nginx.conf 中 配置 了 test size 10k， 那 么 my _ size 将 会 设置 为 10240。 如 果 配 置 为 
test Size 10m;， 则 my_size 会 设置 为 10485760。 


ngx_conf set_ size slot 只 允许 配置 项 后 的 参数 携带 单位 k 或 者 KE、m 或 者 M， 不 允许 有 8g 或 
者 G 的 出 现 ， 这 与 ngx conf set off slot 是 不 同 的 。 


er 注意 在 nex_http_mytest_create_loc_conf 创 建 结 构 体 时 ， 如 果 想 使 用 
ngx_conf set_size_slot， 必 须 把 my_size 初 始 化 为 NGX_CONF_UNSET_SIZE 宏 ， 也 就 是 4.2.1 节 
中 的 语句 “mycf>my_size=NGX_CONF_UNSET SIZE;，， 否 则 ngx_conf set_size slot 在 解析 
时 会 报错 。 


(7) ngx conf set off slot 


如 有 果 和 希望 配置 项 表达 的 含义 是 空间 的 偏 移 位 置 ， 那 么 可 以 使 用 ngx_conf set_off slot 预 设 
方法 。 事 实 上 ，ngx conf set off slot 与 ngx conf set size slot 是 非常 相似 的 ， 最 大 的 区 别 是 
ngx_conf set of 企 slot 文 持 的 参数 单位 还 要 多 1 个 g 或 者 G， 表 示 Gigabyte。 用 


ngx_http_ mytest conf t 结 构 中 的 off tmy o 任 来 存储 参数 ， 解 析 后 的 my_off 表 示 的 偏 移 量 单位 是 
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字 节 。 例 如 : 





static ngx command t ngx http mytest commands[] = { 





{ ngx string("test off"), 
NGX HTTP LOC CONF | NGX CONF TAKE1， 
ngx conf set off slot, NGX HTTP LOC CONF OFFSET, 
offsetof (ngx http mytest conf t, my off), 
NULL }, 
ngx null command 


}; 




















如 果 在 nginx.conf 中 配置 了 test off 1g;， 那 么 my of 将 会 设置 为 1073741824。 当 它 的 单位 
为 kK、K、m、M 时 ， 其 意义 与 ngx conf set size slot 相 同 。 


@ 注意 在 nex_http_mytest_create_loc_conf 创 建 结构 体 时 ， 如 果 想 使 用 
negx_conf_set_off_slot， 必 须 把 my_off 初 始 化 为 NGX_CONF_UNSET 宏 ， 也 就 是 4.2.1 节 中 的 语 


名 “mycf->my_off=NGX_CONF_UNSET;”， 否 则 ngx_conf_set_off_slot 在 解析 时 会 报错 。 
(8) ngx conf set msec slot 


如 果 和 希望 配置 项 表达 的 含义 是 时 间 长 短 ， 那 么 用 ngx conf set_msec slot 来 解析 配置 项 是 
非常 合适 的 ， 因 为 它 文 持 非 常 多 的 时 间 单 位 。 


用 ngx http mytest_conf t 结 构 中 的 ngx msec_tmy msec; 来 存储 参数 ， 解 析 后 的 my msec 表 


示 的 时 间 单 位 是 毫秒 。 事 实 上 ，ngx_msec t 是 一 个 无 符号 整 型 : 








typedef ngx uint t ngx rbtree key t; 
typedef ngx rbtree key t ngx msec t; 








ngx_conf set_msec_slot 解 析 的 配置 项 也 只 能 携带 1 个 参数 。 例 如 : 





static ngx command t ngx http mytest commands[] = { 





{ ngx string("test msec"), 
NGX HTTP LOC CONF | NGX CONF TAKE1， 
ngx conf set msec slot, NGX HTTP LOC CONF OFFSET, 

















offsetof (ngx http mytest conf t, my msec), 
NULL }, 
ngx null command 











如 果 在 nginx.conf 中 配置 了 test msec 1d;， 那 么 my msec 会 设置 为 1 天 之 内 的 守 秒 数 ， 也 就 
是 86400000。 


@ 注意 在 nex_http_mytest_create_loc_conf 创 建 结 构 体 时 ， 如 果 想 使 用 
ngx_conf_ set_msec_slot， 那 么 必须 把 my_msec 初 始 化 为 NGX_CONF_UNSET_MSEC 宏 ， 也 就 
是 4.2.1 节 中 的 语句 “mycf->my_msec=NGX_CONF_UNSET_MSEC;”， 否 则 


ngx_conf set_msec_slot 在 解析 时 会 报错 。 
(9) ngx conf set sec slot 


ngx conf set sec slot 与 ngx conf set msec slot 非 常 相似 ， 只 是 ngx conf set sec slot 在 用 
ngx_http_mytest_conf t 结 构 体 中 的 time_t my_sec; 来 存储 参数 时 ， 解 析 后 的 my_sec 表 示 的 时 间 早 


位 是 秒 ， 而 ngx conf set_msec _ slot 为 宣 秒 。 





static ngx command t ngx http mytest commands[] = { 





{ ngx string("test sec"), 
NGX HTTP LOC CONF | NGX CONF TAKE1， 
ngx conf set sec slot, 
NGX HTTP LOC CONE OFFSET, 
offsetof (ngx http mytest conf t, my sec), 
NULL }, 

ngx null command 


}; 





























如 果 在 nginx.conf 中 配置 了 test_sec 1d;， 那 么 my _sec 会 设置 为 1 天 之 内 的 秒 数 ， 也 就 是 
86400。 


er 注意 在 nex_http_mytest_create_loc_conf 创 建 结 构 体 时 ， 如 果 想 使 用 
ngx_conf set_sec_slot， 那 么 必须 把 my_sec 初 始 化 为 NGX_CONF_UNSET 宏 ， 也 就 是 4.2.1 节 中 
的 语句 “mycf->my_sec=NGX_CONF_UNSET;”， 否 则 ngx_conf _set_sec_slot 在 解析 时 会 报 


错 。 
(10) ngx conf set bufs slot 
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Nginx 中 许多 特有 的 数据 结构 都 会 用 到 两 个 概念 : 单个 ngx_buf t 缓 存 区 的 空间 大 小 和 人 多 
许 的 缓存 区 个 数 。ngx_conf set_bufs_slot 就 是 用 于 设置 它 的 ， 它 要 求 配 置 项 后 必须 携带 两 个 
参数 ， 第 1 个 参数 是 数字 ， 通 常会 用 来 表示 缓存 区 的 个 数 ， 第 2 个 参数 表示 单个 缓存 区 的 空间 
大 小 ， 它 像 ngx_conf set_size_slot 中 的 参数 单位 一 样 ， 可 以 不 携带 单位 ， 也 可 以 使 用 k 或 者 
KK、n 或 者 M 作 为 单位 ， 如 “gzip_buffers 48k;”。 我 们 用 ngx_http_mytest_conf t 结 构 中 的 
ngx bufs tmy bufs; 来 存储 参数 ，ngx bufs t (12.1.3 节 ngx http_upstream conf t 结 构 体 中 的 bufs 
成 员 就 是 应 用 ngx_bufs t 配 置 的 一 个 非常 好 的 例子 的 定义 很 简单 ， 如 下 所 示 。 











typedef struct { 
ngx_int 七 num; 
Size tC Sie 

} ngx bufs t; 





ngx_conf set_bufs_slot 解 析 后 会 把 配置 项 后 的 两 个 参数 转化 成 ngx_bufs_t 结 构 下 的 两 个 成 
员 num 和 size， 其 中 size 以 字 节 为 单位 。 例 如 : 





static ngx command t ngx http mytest commands[] = { 





{ ngx string("test bufs"), 
NGX HTTP LOC CONF | NGX CONF TAKE2, 
ngx conf set bufs slot, NGX HTTP LOC CONF OFFSET, 
offsetof (ngx http mytest conf t, my bufs), 
NULL }, 
ngx _ null command 














}; 





如 果 在 nginx.conf 中 配置 为 test_bufs 41k;， 那 么 my_bufs 会 设置 为 {4,1024}。 
(11) ngx conf set enum slot 


ngx_conf set_enum slot 表示 枚 举 配置 项 ， 也 就 是 说 ，Nginx 模 块 代 码 中 将 会 指定 配置 项 的 
参数 值 只 能 是 已 经 定义 好 的 ngx_conf enum t 数 组 中 name 字 符 串 中 的 一 个 。 先 看 看 
ngx_conf enum t 的 定义 如 下 所 示 。 





typedef struct { 
ngx_str t name; 
ngx uint t value; 
} ngx conf enum t; 











其 中 ，name 表 示 配 置 项 后 的 参数 只 能 与 name 指 向 的 字符 串 相 等 ， 而 value 表 示 如 果 参 数 
中 出 现 了 name，ngx_conf set enum slot 方 法 将 会 把 对 应 的 value 设 置 到 存储 的 变量 中 。 例 如 : 





static ngx conf enum t test enums[] = { 
{ ngx string("apple"), 1 }, 
{ ngx string("banana"), 2 1}, 
{ ngx string("orange"), 3 1}, 
{ ngx null string, 0 } 
}; 





上 面 这 个 例子 表示 ， 配 置 项 中 的 参数 必须 是 apple、banana、orange 其 中 之 一 。 注 意 ， 必 
须 以 nex null _ string 结尾 。 需 要 用 ngx uint t 来 存储 解析 后 的 参数 ， 在 4.2.1 节 中 是 用 
ngx_http_mytest_conf t 中 的 “ngx_vint tmy_enum seq;” 来 存储 解析 后 的 枚 举 参数 的 。 在 设置 
ngx_command t 时 ， 需 要 把 上 面 例子 中 定义 的 test_enums 数 组 传 给 post 指 针 ， 如 下 所 示 。 





static ngx command t ngx http mytest commands[] = { 





{ ngx string("test enum"), 
NGX HTTP LOC CONF | NGX CONF TRAKE1， 
ngx conf set enum slot, NGX HTTP LOC CONF OFFSET, 
offsetof (ngx http mytest conf t, my enum seq), 
test enums }, 

ngx null command 




















}; 





这 样 ， 如 果 在 nginx.conf 中 出 现 了 配置 项 test enum banana;，my enum seq 的 值 是 2。 如 果 
配置 项 test enum 出 现 了 除 apple、banana、orange 之 外 的 值 ，Nginx 将 会 报 “invalid value” 错 误 。 


(12) ngx conf set bitmask slot(ngx conf t*cfngx command t*cmd,void*conf); 


ngx_conf set bitmask slot 与 ngx conf set enum slot 也 是 非常 相似 的 ， 配 置 项 的 参数 都 必 
须 是 枚 举 成 员 ， 唯 一 的 差别 在 于 效率 方面 ，ngx_conf set_enum slot 中 枚 举 成 员 的 对 应 值 是 整 
型 ， 表 示 序 列 号 ， 它 的 取 值 范围 是 整 型 的 范围 ， 而 ngx_conf set_bitmask slot 中 枚 举 成 员 的 对 
应 值 虽然 也 是 整 型 ， 但 可 以 按 位 比较 ， 它 的 效率 要 高 得 多 。 也 就 是 说 ， 整 型 是 4 字 节 (32 
位 ) 的话， 在 这 个 枚 举 配 置 项 中 最 多 只 能 有 32 项 。 








由 于 ngx conf set bitmask slot 与 ngx conf set enum slot 这 两 个 预 设 解 析 方法 在 名 称 上 的 


口 由 掉 所有 由 和 所 掉 由 http' /wNv inuxorobe, con 





差别 ， 用 来 表示 配置 项 参数 的 枚 举 取 值 结构 体 也 由 ngx_conf enum t 变 成 了 
ngx_conf bitmask t， 但 它们 并 没有 区 别 。 





typedef struct { 
ngx str t name; 
ngx uint t mask; 
} ngx conf bitmask t; 





下 面 以 定义 test_bitmasks 数 组 为 例 来 进行 说 明 。 





static ngx conf bitmask t test bitmasks[] = { 
{ ngx string("good"), 0x0002 }, 
{ ngx string("better"), Ox0004 }, 
{ ngx string("best"), Ox0008 1}, 
{ ngx null string, 0 } 
}; 





如 果 配 置 项 名 称 定义 为 test_bitmask， 在 nginx.conf 文 件 中 test_bitmask 配 置 项 后 的 参数 只 能 
是 good、better、best 这 3 个 值 之 一 。 我 们 用 ngx http mytest conf t 中 的 以 下 成 员 : 





ngx uint 七 my_bitmask; 





来 存储 test_bitmask 的 参数 ， 如 下 所 示 。 





static ngx command t ngx http mytest commands[] = { 





{ ngx string("test bitmask"), 
NGX_ HTTP LOC CONF | NGX CONF TAKE1， 
ngx conf set bitmask slot, 
NGX HTTP LOC CONF OFFSET, 
offsetof (ngx http mytest conf t, my bitmask), 
test bitmasks }, 
ngx null command 


}; 


























如 果 在 nginx.conf 中 出 现 配置 项 test bitmaskbest， 那 么 my bitmask 的 值 是 0x8。 
(13) ngx conf set access Slot 


ngx_conf set_access_slot 用 于 设置 读 / 写 权限 ， 配 置 项 后 可 以 携带 1~3 个 参数 ， 因 此 ， 在 
ngx command t 中 的 type 成 员 要 包 仿 NGX CONF TAKE123。 参 数 的 取 值 可 参见 表 4-2。 这 里 用 
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ngx_http_mytest_conf t 结 构 中 的 “ngx uint tmy access;” 来 存储 配置 项 “test _ access” 后 的 参数 
值 ， 如 下 所 示 。 





static ngx command t ngx http mytest commands[] = { 





{ ngx string("test access"), 
NGX HTTP LOC CONF | NGX CONF TAKE123, 
ngx conf set access slot, 
NGX HTTP LOC CONE OFFSET, 
offsetof (ngx http mytest conf t, my access), 
NULL }, 

ngx null command 


}; 





























这 样 ，ngx_conf set_access_slot 就 可 以 解析 读 / 写 权限 的 配置 项 了 。 例 如 ， 当 nginx.conf 中 


出 现 配 置 项 test_access user:rw group:rw all:f; 时 ，my access 的 值 将 是 436。 


@ 注意 在 nex_http_mytest_create_loc_conf 创 建 结 构 体 时 ， 如 果 想 使 用 
ngx_conf set_access_slot， 那 么 必须 把 my_access 初 始 化 为 NGX_CONF_UNSET_UINT 宏 ， 也 就 
是 4.2.1 节 中 的 语句 “mycf->my_access=NGX_CONF_UNSET_UINT;”， 否 则 


nogx_conf set_access_slot 解 析 时 会 报错 。 
(14) ngx conf set path slot 


ngx_conf set_path slot 可 以 携带 1~4 个 参数 ， 其 中 第 1 个 参数 必须 是 路 径 ， 第 2~4 个 参数 必 
须 是 整数 (大 部 分 情形 下 可 以 不 使 用 ) ， 可 以 参见 2.4.3 市 中 client_ body temp_ path 配置 项 的 
用 法 ，client body _temp_path 配 置 项 就 是 用 ngx_conf set path_ slot 预 设 方法 来 解析 参数 的 。 


ngx_conf set path_ slot 会 把 配置 项 中 的 路 径 参 数 转化 为 ngx_path t 结 构 ， 看 一 下 ngx_path t 
的 定义 。 





typedef struct { 
ngx_ str t name; 
size 七 len; 
size 七 Llevel[3]; 
ngx path manager pt manager; 
ngx path loader pt loader; 
void data; 
char conf file; 
ngx uint t line; 
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其 中 ，name 成 员 存储 着 字符 串 形 式 的 路 径 ， 而 level 数 组 就 会 存储 着 第 2、 第 3、 第 4 个 参 
数 〈 如 果 存 在 的 话 ) 。 这 里 用 ngx http_mytest conf t 结 构 中 的 “ngx path t*my path;” 来 存储 配 
置 项 “test _ path” 后 的 参数 值 。 





static ngx command t ngx http mytest commands[] = { 





{ ngx string("test path"), 
NGX HTTP LOC CONEF | NGX CONF TAKE1234， 














ngx conf set path slot, 
NGX HTTP LOC CONE OFFSET, 
offsetof (ngx http mytest conf t, my path), 














NULL }, 
ngx null command 


}; 





如 果 nginx.conf 中 存在 配置 项 test_path/usr/local/nginx/123;，my_path 指 癌 的 ngx_path t 结 构 
中 ，name 的 内 容 是 /usr/local/nginx/， 而 level[0] 为 1，level[1] 为 2，level[2] 为 3。 如 果 配 置 项 
是 “test_path/usr/local/nginx/;”， 那 么 level 数 组 的 3 个 成 员 都 是 0。 


4.2.4” 自 定义 配置 项 处 理 方法 


除了 使 用 Nginx 已 经 实现 的 14 个 通用 配置 项 处 理 方法 外 ， 还 可 以 自己 编写 专用 的 配置 项 
处 理 方 法 。 事 实 上 ，3.5 市 中 的 ngx_http_mytest 就 是 目 定 义 的 处 理 mytest 配 置 项 的 方法 ， 只 是 没 
有 去 处 理 配 置 项 的 参数 而 已 。 本 节 举 例 说 明 如 何 编写 方法 来 解析 配置 项 。 


假设 我 们 要 处 理 的 配置 项 名 称 是 test config， 它 接收 1 个 或 者 2 个 参数 ， 且 第 1 个 参数 类 型 
是 字符 串 ， 第 2 个 参数 必须 是 整 型 。 定 义 结构 体 来 存储 这 两 个 参数 ， 如 下 所 示 。 





typedef struct { 
ngx str t my config str; 
ngx int t my config num; 
} ngx http mytest conf 七 














其 中 ，my_config str 存 储 第 1 个 字符 串 参 数 ，my_config num 存储 第 2 个 数字 参数 。 


自 光 ， 我 们 按照 4.2.2 Fingx_command s 中 的 set 万 法 指针 格式 来 定义 这 个 配置 项 处 理 方 
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法 ， 如 下 所 示 。 





static char* ngx conf set myconfig(ngx conf t cf, ngx commana t cmd, void *conf); 





接 下 来 定义 ngx command tt 结构 体 ， 如 下 所 示 。 








static ngx command t ngx http mytest commands[] = { 


{ ngx string("test myconfig"), 
NGX HTTP LOC CONF | NGX CONF TAKE12, 
ngx conf set myconfig, 
NGX HTTP LOC CONE OFFSET, 
0, 
NULL }, 
ngx null command 

















}; 





这 样 ，test_myconfig 后 就 必须 跟着 1 个 或 者 2 个 参数 了 。 现 在 开始 实现 
ngx_conf set myconfig 处 理 方法 ， 如 下 所 示 。 





static char* ngx conf set myconfig(ngx conf t cf, ngx command t cmd, void conf) 


/注意 ， 参 数 


conf 就 是 


HTTP 框 架 传 给 用 户 的 在 


ngx http mytest create loc conf 回 调 方法 中 分 配 的 结构 体 





ngx http mytest conf 七 x/ 
ngx http mytest conf t mycf = conf; 
/ cf->args 是 








1 个 

ngx_array 七 队列 ， 它 的 成 员 都 是 
ngx_str 七 结构 。 我 们 用 

Value 指向 

ngx array 七 的 


elts 内 容 ， 其 中 
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value[1] 就 是 第 


1 个 参数 ， 同 理 ， 


value[2] 是 第 


2 个 参数 


ngx str t value = cf->args->elts; 
// ngx array 的 


nelts 表 示 参 数 的 个 数 


if (cf->args->nelts > 1) 
t 
// 直接 赋值 即 可 ， 


ngx_str 七 结构 只 是 指针 的 传递 


mycf->my config str = Value[1]， 
} 
if (cf->args->nelts > 2) 
{ 

// 将 字符 串 形 式 的 第 


2 个 参数 转 为 整 型 


mycf->my config num = ngx atoi(value[2] .data, value[2].1en); 


/* 如 果 字 符 囊 转化 整 型 失败 ， 将 报 “ 


invalid number” 和 错误 ， 


Nginx 启 动 失败 


# 





if (mycf->my config num == NGX ERROR) { 
return "invalid number"; 
} 
} 
// 返回 成 功 


return NGX CONF OR; 





假设 nginx.conf 中 出 现 test_myconfigjordan 23; 配 置 项 ， 那 么 my_config str 的 值 是 jordan， 而 
my_config num 的 值 是 23。 
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4.2.5 合并 配置 项 


回顾 一 下 4.1 节 中 的 例子 ， 一 个 test_str 配 置 同时 在 http{...}、server{...}、l]ocation/urll {...} 
中 出 现时 ， 到 底 以 哪 一 个 为 准 ? 本 市 将 讨论 如 何 合 并 不 同 配置 块 间 的 同名 配置 项 ， 首 先 回顾 
一 下 4.2.1 节 中 ngx http module t 的 结构 。 





typedef struct { 


void (create loc conf) (ngx conf t cf); 
char (*merge loc conf) (ngx conf t cf void prev, void *conf); 


} ngx http module t; 





上 面 这 段 代 人 码 定义 了 create_loc_conf 方 法 ， 意 味 着 HTTP 框 染 会 建 并 loc 级 别 的 配置 。 什 么 
意思 呢 ? 就 是 说 ， 如 果 没 有 实现 merge loc conf 方 法 ， 也 就 是 在 构造 ngx http module t 时 将 
merge_loc_conf 设 为 NULL 了 ， 那 么 在 4.1 市 的 例子 中 server 块 或 者 http 块 内 出 现 的 配置 项 都 不 会 
生效 。 如 果 我 们 希望 在 server 块 或 者 http 块 内 的 配置 项 也 生效 ， 那 么 可 以 通过 merge loc_conf 
方法 来 实现 。merge_loc_conf 会 把 所 属 父 配置 块 的 配置 项 与 子 配置 块 的 同名 配置 项 合并 ， 当 
然 ， 如 何 合 并 取决 于 具体 的 merge_loc_conf 实 现 。 








merge_loc_conf 有 3 个 参数 ， 第 1 个 参数 仍然 是 ngx_conf t*cf， 提 供 一 些 基本 的 数据 结构 ， 
如 内 存 池 、 日 志 等。 我 们 需要 关注 的 是 第 >、 第 3 个 参数 ， 其 中 第 2 个 参数 void*prev 是 指 解析 
父 配置 块 时 生成 的 结构 体 ， 而 第 3 个 参数 void*con{ 则 指出 的 是 保存 子 配置 块 的 结构 体 。 


仍 以 4.1 市 的 例子 为 例 ， 来 看 看 如 何 合并 同时 出 现 了 6 次 的 test_str 配 置 项 ， 如 下 所 示 。 





static char * 
ngx http mytest merge loc conf (ngx conf t cf void parent, void *child) 
{ 





ngx http mytest conf 七 Pre = (ngx http mytest conf t )parent; 
ngx http mytest conf 七 conf = (ngx http mytest conf t )chilgd; 
ngx conf merge str Va Me (con my Se, 

prev->my _ str, "defaultstr"); 

















return NGX CONF ORK; 
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可 以 看 到 ， 只 需要 按照 自己 的 需求 将 父 配置 块 的 值 赋予 子 配置 块 即 可 ， 这 时 表示 父 配置 
块 优先 级 更 高 ， 反 过 来 也 是 可 以 的 ， 表 示 子 配置 块 的 优先 级 更 高 。 例 如 ， 在 解析 servert...} 
块 时 《〈 传 入 的 child 参 数 就 是 当前 server 块 的 ngx_http_mytest_ conf t 结 构 ) ， 父 配置 块 〈 也 就 是 
传 入 的 parent 参 数 ) 就 是 http{...} 块 ， 解析 1ocation{...} 块 时 父 配置 块 就 是 server{...} 块 。 


如 何 处 理 父 、 子 配置 块 下 的 同名 配置 项 ， 每 个 HTTP 模 块 都 可 以 自由 选择 。 例 如 ， 可 以 
简单 地 以 父 配置 替换 子 配 置 ， 或 者 将 两 种 不 同 级 别 的 配置 做 完 运算 后 再 覆盖 等 。 上 面 的 例子 
对 不 同 级 别 下 的 test_str 配 置 项 的 处 理 是 最 简单 的 ， 下 面 我 们 使 用 Nginx 预 置 的 
ngx_conf merge _str_value 宏 来 合并 子 配 置 块 中 ngx_str_t 尖 型 的 my _ str 成 员 ， 看 看 
ngx_conf merge_str_value 到 底 做 了 哪些 事情 。 














#define ngx conf merge str value (conf, prev, default) \ 


// 当前 配置 块 中 是 否 已 经 解析 到 





test _ str 配置 项 


if (conf.data == NULL){ \ 
// 父 配置 块 中 是 否 已 经 解析 到 


test _ str 配置 项 


if (prev.data) { \ 
// 将 父 配置 块 中 的 


test str 参 数值 直接 窗 盖 当前 配置 块 的 


test str 
conf.len = prev.len; SN 
conf.data = prev.data; \ 
} else { N\ 


/* 如 果 父 配置 块 和 子 配置 块 都 没有 解析 到 


test strs 议 


default 参 数 作 为 默认 值 传 给 当前 配置 块 的 


test str*/ 
conf.len = sizeof(default) - 1; \ 





conf.data = (u char *) default; \ 
\ 








事实 上 ，Nginx 预 设 的 配置 项 合并 方法 有 10 个 ， 它 们 的 行为 与 上 述 的 
ngx conf merge str value 是 相似 的 。 参 见 表 4-5 中 Nginx 己 经 实现 好 的 10 个 简单 的 配置 项 合 
宏 ， 它 们 的 参数 类 型 与 ngx conf merge_str_value 一 致 ， 而 且 除 了 ngx conf merge bufs value 


外 ， 它 们 都 将 接收 3 个 参数 ， 


配置 项 合并 宏 


ngx conf merge value 


ngx conf merge ptr_value 


ngx conf merge uint value 


ngx conf merge msec value 


配置 项 合并 宏 


ngx conf merge sec value 


ngx conf merge size value 


ngx conf merge off value 





ngx conf merge str value 


ngx conf merge bufs value 


ngx conf merge bitmask value 


分 别 表示 父 配置 块 参数 、 子 配置 块 参数 、 默 认 值 。 


表 45 Nginx 预 设 的 10 种 配置 项 合并 宏 


义 

合并 可 以 使 用 等 号 (=) 直接 赋值 的 变量 ， 并 且 该 变量 在 create_ loc_conf 等 
分 配方 法 中 初始 化 为 NGX_CONF _UNSET， 这 样 类 型 的 成 员 可 以 使 用 ngx_ 
conf merge_value 合并 安 


省 


合并 指针 类 型 的 变量 ， 并 且 该 变量 在 create loc_conf 等 分 配方 法 中 初始 化 
为 NGX_ CONEF _ UNSET_ PTR， 这 样 类 型 的 成 员 可 以 使 用 ngx_conf merge_ptr_ 
value 合并 安 

合并 整数 类 型 的 变量 ， 并 且 该 变量 在 create_ loc_conf 等 分 配方 法 中 初始 化 为 
NGX CONF UNSET_OINT, 这 样 类 型 的 成 员 可 以 使 用 Ra 


value 合并 切 


上 


合并 表示 : 是 各 的 ngx_msec t 类 型 的 变量 ， 并 且 该 变量 在 create loc_conf 等 
分 配方 法 中 初始 化 为 NGX_CONEF _ UNSET MSEC， 这 样 类 型 的 成 员 可 以 使 用 


ngx_conf merge_msec_value 合并 安 


意 义 
合并 表示 秒 的 time_t 类 型 的 变量 ， 并 且 该 变量 在 create loc_conf 等 分 配方 法 
中 初始 化 为 NGX_CONEF _UNSET， 这 样 类 型 的 成 员 可 以 使 用 ngx_conf merge_ 
sec_value 合并 安 
合并 size t 等 表示 空间 长 度 的 变量 ， 并 且 该 变量 在 create loc_conf 等 分 配 
方法 中 初始 化 为 NGX_CONEF UNSET _ SIZE， 这 样 类 型 的 成 员 可 以 使 用 ngx_ 


conf merge size_value 合并 安 


合并 off t 等 表示 偏 移 量 的 变量 ， 并 且 该 变量 在 create loc_conf 等 分 配方 法 
中 a 始 化 为 NGX_CONEF_UNSET， 这 样 类 型 的 成 员 可 以 使 用 ngx_conf merge_ 
off value 合并 安 
ngx_str t 类 型 的 成 员 可 以 使 用 ngx_conf merge_str_value 合并 ， 这 时 传人 的 
default 参数 必须 是 一 个 char* 字符 串 
ngx_bufs t 类 型 成 员 可 以 使 用 ngx_conf merge_bufs_value 合并 安 ， 这 时 传 
人 的 default 参数 是 两 个 ， 因 为 ngx_bufs t 类 型 有 两 个 成 员 ， 所 以 需要 传人 两 
个 默认 值 
` 进 制 位 来 表示 标志 位 的 整 型 成 员 ， 可 以 使 用 ngx_conf merge_bitmask 
value 合并 安 
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在 4.3.3 市 中 我 们 会 看 到 HTTP 框 染 在 什么 时 候 会 调用 各 模块 的 merge_loc_conf 方 法 或 者 
merge srv_conf 方 法 。 
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4.3 ” HTTP 配置 模型 


上 文中 我 们 了 解 了 如 何 使 用 Nginx 提 供 的 预 设 解析 方法 来 处 理 自 己 感 兴趣 的 配置 项 ， 由 
于 http 配 置 项 设计 得 有 些 复杂 ， 为 了 更 清晰 地 使 用 好 ngx_command tt 结 构 体 处 理 http 配 置 项 ， 
本 市 将 简单 讨论 HTTP 配 置 模 型 是 怎样 实现 的 ， 在 第 10 半 我 们 会 从 HTTP 框 染 的 角度 谈 谈 它 是 
怎么 管理 每 一 个 HTTP 模 块 的 配置 结构 体 的 。 


当 Nginx 检 测 到 http{...} 这 个 关键 配置 项 时 ，HTTP 配 置 模型 就 启动 了 ， 这 时 会 首先 建立 1 
个 ngx_http_conf ctx t 结 构 。 下 面 看 一 下 ngx_http_conf ctx t 的 定义 。 





typedef struct { 
/* 指 针 数 组 ， 数 组 中 的 每 个 元 素 指向 所 有 


HTTP 模 块 
create main conf 方 法 产生 的 结构 体 


?4 
void *main conf; 


二 
/* 指 针 数 组 ， 数 组 中 的 每 个 元 素 指向 所 有 
HTTP 模 块 
create srv_conf 方 法 产生 的 结构 体 


4 
void *srv conf; 


/* 指 针 数 组 ， 数 组 中 的 每 个 元 素 指 向 所 有 
HTTP 模 块 
create loc conf 方 法 产生 的 结构 体 


/ 
void *]loc conf; 
} ngx http conf ctx 七 








这 时 ，HTTP 框 架 会 为 所 有 的 HTTP 模 块 建 六 3 个 数组 ， 分 别 存 放 所 有 HTTP 模 块 的 
create main conf、create srv_conf、create loc_conf 方 法 返回 的 地 址 指针 《〈 歌 像 本 章 的 例子 中 
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mytest 模 块 在 create loc_conf 中 生成 了 ngx http mytest conf 结构， 并 在 create loc_conf 方 法 返 
回 时 将 指针 传递 给 HTTP 框 架 ) 。 当 然 ， 如 果 HTTP 模 块 对 于 配置 项 不 感 兴趣 ， 它 没有 实现 
create main conf、create_srv_conf、create loc_conf 等 方法 ， 那 么 数组 中 相应 位 置 存储 的 指针 
是 NULL。negx http conf ctx t 的 3 个 成 员 main conf、srv_conf、loc conf 分 别 指向 这 3 个 数组 。 
下 和 面 看 一 段 简化 的 代码 ， 了 解 如 何 设 置 create_loc_conf 返 回 的 地 址 。 





ngx http conf ctx t, *otx; 
// HTTP 框 架 生成 了 





1 


ngx http conf ctx 七 结构 





ctx = ngx pcalloc (cf->pool, sizeof (ngx http conf ctx t)); 
if (ctx == NULL) { 
return NGX CONF ERROR; 
} 
// 生成 








1 个 数组 存储 所 有 的 


HTTP 模 块 


create loc conf 方 法 返回 的 地 址 


ctx->loc conf = ngx pcalloc(cf->pool, sizeof(void *) * ngx http max module); 
if (ctx=>loc conf == NULL) { 
return NGX CONF ERROR; 





} 
// 遍历 所 有 的 


HTTP 模 块 


for (m= 0; ngx modules[m]; m++) { 
if (ngx modules[m]->type != NGX HTTP MODULE 
continue; 





一 


} 
module = ngx modules[m]->ctx; 
mi = ngx modules[m]->ctx index; 


/* 如 果 这 个 
HTTP 模 块 实现 了 
create loc conf， 就 调用 它 ， 并 把 返回 的 地 址 存储 到 


loc conf 中 
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«yf 
if (module->create loc conf) { 
ctx->loc conf[mi] = module->create loc conf (cf); 
if (ctx->loc conf[mi] == NULL) { 
return NGX CONF ERROR; 








} 





这 样 ， 在 http{...} 块 中 就 通过 1 个 ngx_http_conf ctx 结构 保 存 了 所 有 HTTP 模 块 的 配置 数据 
结构 的 入 口 。 以 后 过 到 任何 servert.. Liane .} 块 时 ， 也 会 建立 ngx http_ conf ctx tt 结 
构 ， 生 成 同样 的 数组 来 保存 所 有 HTTP 模 块 通过 create_srv_conf、create_loc_conf 等 方法 返回 的 
旨 针 地 址 。ngx_http_conf ctx t 是 了 解 http 配 置 块 的 基础 ， 下 面 我 们 来 看 看 具体 的 解析 流程 。 


4.3.1 解析 HITP 配 置 的 流程 





图 4-1 是 HTTP 框 架 解 析 配 置 项 的 示意 流程 图 (图 中 出 现 了 ngx_http_module 和 
ngx_http_core _ module 模块 ， 所 谓 的 HTTP 框 架 主 要 由 这 两 个 模块 组 成 ) ， 下 面 解释 图 中 每 个 
流程 的 意义 。 
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ngx_http _module ngx_http _core _module mytest 模块 


1 1. 解析 配置 文件 1 | | | 
六 
i | | | 
| 
| 3. 初 始 化 每 一 个 HTTP 模 块 | 
| 4. 依次 调用 各 模块 的 create _ (main 、srv 、loc ) _conf 
| | | 
| | 和 | 
Wee ee ye 下 
| 6. NO | 
| | 
| | en | 
| 1< 一 ie ol 
8. 开始 解析 http 块 下 的 配 置 项 


| 
| 

| | | 
L 9. 检测 到 Es 后 ， 饥 历 世 有 宰 咽 的 所 有 command | 
| 10. 根据 command 描述 , 回调 相应 的 方法 | 
| 

| 

| 








| 
| | | 
| 1 11. 配置 项 处 理 完 毕 1 
本 osm et tl, ON 
一 | I | 
12. 发 现 server 配置 项 | | 
| | 
13. 依次 调用 各 模块 的 create _ (srv | loc ) _conf 
| 
| | 
| 14. 返回 分 本 好 的 内 存 指针 
| ie 
| 15. 开始 解析 server 块 下 的 配置 项 
| | | 
| | | | 
a 16. 依 此 类 失 
| 
| | 
18. server pp | | 
RE = | 
FE I | 
19. http 配置 项 处 理 完 与 毕 ， [ | 
' I | | 
| | 
| 人 > oem 
| 
21. http 本 置 项 处 理 完毕 ， 
En | | | 


22. 配置 项 处 理 完 毕 | 
| 
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1) 图 4-1 中 的 主 循环 是 指 Nginx 进 程 的 主 循环 ， 主 循环 只 有 调用 配置 文件 解析 融 才 能 解 
析 mginx.conf 文 件 《〈《 这 里 的 “ 主 循环 ”是 指 解析 全 部 配置 文件 的 循环 代码 ， 图 8-6 的 第 4 步 ， 为 了 
便于 理解 ， 可 以 认为 是 Nginx 框 架 代 人 码 在 循环 解析 配置 项 )。 


2) 当 发 现 配 置 文件 中 含有 http{} 关 键 字 时 ，HTTP 框 架 开始 启动 ， 这 一 过 程 详 见 10.7 节 描 
述 的 ngx http block 方 法 。 


3) HTTP 框 染 会 初始 化 所 有 HTTP 模 块 的 序列 号 ， 并 创建 3 个 数组 用 于 存储 所 有 HTTP 模 
块 的 create main conf、create srv_conf、create loc_conf 方 法 返回 的 指针 地 址 ， 并 把 这 3 个 数 
组 的 地 址 保存 到 ngx http_conf ctx tt 结构 中 。 


4) 调用 每 个 HTTP 模 块 〈 当 然 也 包括 例子 中 的 mytest 模 块 ) 的 create_ main_conf、 
create_STV_conf、create loc_conf (如 果实 现 的 话 ) 方法 。 


5) 把 各 HTTP 模 块 上 述 3 个 方法 返回 的 地 址 依次 保存 到 ngx_http_conf_ctx_t 结 构 体 的 3 个 数 
组 中 。 


6) 调用 每 个 HTTP 模 块 的 preconfiguration 方 法 〈 如 果实 现 的 话 ) 。 
7) 注意 ， 如 果 preconfiguration 返 回 失败 ， 那 么 Nginx 进 程 将 会 停止。 


8) HTTP 框 染 开始 循环 解析 nginx.conf 文 件 中 http{.….} 里 面 的 所 有 配置 项 ， 注 意 ， 这 个 过 


程 到 第 19 步 才 会 返回 。 





9) 配置 文件 解析 器 在 检测 到 1 个 配置 项 后 ， 会 损 历 所 有 的 HTTP 模块， 检查 它们 的 
ngx command t 数 组 中 的 name 项 是 否 与 配置 项 名 相同 。 


10) 如 果 找 到 有 1 个 HTTP 模块 《如 mytest 模 块 ) 对 这 个 配置 项 感 兴 趣 〈 如 test myconfig 配 
置 项 ) ， 就 调用 ngx_ command tt 结构 中 的 set 方 法 来 处 理 。 
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12) 配置 文件 解析 堪 继续 检测 配置 项 。 如 果 发 现 server{...} 配 置 项 ， 就 会 调用 
ngx http core _ module 模块 来 处 理 。 因 为 ngx http core module 模 块 明确 表示 希望 处 理 servert{} 
块 下 的 配置 项 。 注 意 ， 这 次 调用 到 第 18 步 才 会 返回 。 


13) ngx http core module 模 块 在 解析 server{...} 之 前 ， 也 会 如 第 3 步 一 样 建 立 
ngx_http_conf ctx t 结 构 ， 并 建立 数组 保存 所 有 HTTP 模 块 返回 的 指针 地 址 。 然 后 ， 它 会 调用 
每 个 HTTP 模 块 的 create srv conf、create loc conf 方 法 (如 果实 现 的 话 ) 。 


14) 将 上 一 步 各 HITP 模 块 返回 的 指针 地 址 保存 到 ngx_http_conf ctx_t 对 应 的 数组 中 。 


15) 开始 调用 配置 文件 解析 器 来 处 理 server{...} 里 面 的 配置 项 ， 注 意 ， 这 个 过 程 在 第 17 
返回 。 


中 


16) 继续 重复 第 9 步 的 过 程 ， 人 遍历 nginx.conf 中 当前 server{...} 内 的 所 有 配置 项 。 





17) 配置 文件 解析 器 继续 解析 配置 项 ， 发 现 当 前 server 块 已 经 衣 历 到 尾部 ， 说 明 server 块 
内 的 配置 项 处 理 完 毕 ， 返 回 ngx http core module 模 块 。 


18) http core 模 块 也 处 理 完 server 配 置 项 了 ， 返 回 至 配置 文件 解析 堪 继 续 解 析 后 面 的 配置 
项 。 


19) 配置 文件 解析 器 继续 解析 配置 项 ， 这 时 发 现 处 理 到 了 http{.….} 的 尾部 ， 返 回 给 HTTP 
框架 继续 处 理 。 





20) 在 第 3 步 和 第 13 步 ， 以 及 我 们 没有 列 出 来 的 某 些 步骤 中 《如 发 现 其 他 server 块 或 者 
location 块 ) ， 都 创建 了 ngx http_ conf ctx tt 结构， 这 时 将 开始 调用 merge_srv_conf、 
merge loc conf 等 方法 合并 这 些 不 同 块 (http、server、location〉 中 每 个 HTTP 模 块 分 配 的 数据 
结构 。 


21) HTTP 框 架 处 理 完 毕 http 配 置 项 〈 也 就 是 ngx_command tt 结构 中 的 set 回 调 方 法 处 理 完 
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毕 ) ， 返 回 给 配置 文件 解析 恬 继 续 处 理 其 他 http {..} 外 的 配置 项 。 


22) 配置 文件 解析 器 处 理 完 所 有 配置 项 后 会 告诉 Nginx 主 循环 配置 项 解析 完毕 ， 这 时 
Nginx 才 会 局 动 Web 服 务 器 。 








@ 注意 ”图 4-1 并 没有 列 出 解析 location{...} 块 的 流程 ， 实 际 上 ， 和 解析 location 与 解析 server 
并 没有 本 质 上 的 区 别 ， 为 了 简化 起 见 ， 没 有 把 它 画 到 图 中 。 


4.3.2 HITP 配 置 模型 的 内 存 布局 


了 解 内 存 布局 ， 会 帮助 理解 使 用 create_ main conf、create srv conf、create loc conf 等 方 
法 在 内 存 中 创建 了 多 少 个 存放 配置 项 的 结构 体 ， 以 及 最 终 处 理 请 求 时 ， 使 用 到 的 是 哪个 结构 
体 。 我 们 已 经 看 到 ，http 人 f} 块 下 有 1 个 ngx http_conf ctx 结构 ， 而 每 一 个 server{} 块 下 也 有 1 个 
ngx_http_conf ctx t 结 构 ， 它 们 的 关系 如 图 4-2 所 示 。 


图 4-2 摘 述 了 http 块 与 某 个 server 块 下 存储 配置 项 参数 的 结构 体 间 的 关系 。 某 个 server 块 下 
ngx_http_conf ctx t 结 构 中 的 main_conf 数 组 将 通过 直接 指向 来 复 用 所 属 的 http 块 下 的 main_conf 
数组 (其 实 是 说 server 块 下 没有 main 级 别 配置 ， 这 是 显然 的 ) 。 





可 以 看 到 ，ngx http_conf ctx 结构 中 的 main conf、srv_conf、1loc_conf 数 组 保存 了 所 有 
HTTP 模 块 使 用 create main conf、create srv conf、create loc conf 方 法 分 配 的 结构 体 地 址 。 
个 HTTP 模 块 都 有 自己 的 序号 ， 如 第 1 个 HTTP 模 块 就 是 ngx_http_core_module 模 块 。 当 在 
http{..….} 内 珊 历 到 第 2 个 HTTP 模 块 时 ， 这 个 HTTP 模 块 已 经 使 用 create_main conf、 
create_STV_conf、create loc_conf 方 法 在 内 存 中 创建 了 3 个 结构 体 ， 并 把 地 址 放 到 了 
ngx_http_conf ctx t 内 3 个 数组 的 第 2 个 成 员 中 。 在 解析 server{...} 块 时 遍历 到 第 2 个 HTTP 模 块 
时 ， 除 了 不 调用 create_main_conf 方 法 外 ， 其 他 完全 与 http{...} 内 的 处 理 一 致 。 


当 解 析 到 location{..} 块 时 ， 也 会 生成 1 个 ngx http conf ctx t 结 构 ， 其 中 的 3 个 指针 数组 与 
NNn httpo://ww linuxorobe. con 





server{...}、http{...} 块 内 ngx http conf ctx 结构 的 关系 如 图 4-3 所 示 。 


从 图 4-3 可 以 看 出 ， 在 解析 location{...} 块 时 只 会 调用 每 个 HTTP 模 块 的 create_loc_conf 方 法 
创建 存储 配置 项 参数 的 内 存 ，ngx_http_conf ctx t 结 构 的 main conf 和 srv_conf 都 直接 引用 其 所 
属 的 server 块 下 的 ngx_http_conf ctx t 结 构 。 这 也 是 显然 的 ， 因 为 location{...} 块 中 当然 没有 
main 级 别 和 srv 级 别 的 配置 项 ， 所 以 不 需要 调用 各 个 HTTP 模 块 的 create_main_conf、 
create_srv_conf 方 法 生成 结构 体 存放 main、srv 配 置 项 。 
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http 块 下 的 ngx_http _conf _ctx _t 


所 有 HTTP 模 块 create 
_main_conf 产生 的 指针 


= 
| 





第 2 个 HTTP 模 二 主 所 有 HTTP 模 块 create_srvy _conf 产生 的 指针 
main 级别 配置 、 由 





CE 
create _main conf 分 指针 1| 指针 2 |  % | 
i 
所 有 HTTP 模 块 create_loc _conf 产生 的 指针 
;2 个 HTTP 模 块 


i ES 
main 级 别 配置 、 由 Wi 


create _srv_conf 分 配 


的 结构 体 


C7 





第 2 不 HITE 模 英 存 全 基 个 server 块 下 的 ngx_http _conf _ctx _t 
main 级 别 配 置 、 由 
create _loc_conf 分 配 


所 有 HTTP 模 块 create__srv_conf 产生 的 指针 





| 
指针 1| 指针 | -… 


所 有 HTTP 模 块 create_loc conf 产生 的 指针 


指针 1 指针 





第 2 个 HTTP 模 块 存 储 
srv 级 别 配置 、 由 
create _srv_conf 分 配 


的 结构 体 






srv 级 别 配 置 、 由 


create _loc __conf 分配 
的 结构 体 





图 4-2 http 块 与 setrvet 块 下 的 ngx_http_conf_ctx_t 所 指向 的 内 存 间 的 关系 


图 4-2 和 图 4-3 说 明了 一 个 事实 : 在 解析 nginx.conf 配 置 文件 时 ， 一 旦 解析 到 http 人 j 块 ， 将 
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会 调用 所 有 HTTP 模 块 的 create main conf、create srv conf、create loc_conf 方 法 创建 3 组 结构 
体 ， 以 便 存 放 各 个 HTTP 模 块 感 兴趣 的 main 级 别 配 置 项 ， 在 解析 a 到 任何 一 个 server 缮 块 时 ， 双 
会 调用 所 有 HTTP 模 块 的 create srv_conf、create loc conf 方 法 创建 两 组 结构 体 ， 以 存放 各 个 
HTTP 模 块 感 兴趣 的 srv 级 别 配置 项 ， 在 解析 到 任何 一 个 locationf} 块 时 ， 则 会 调用 所 有 HTTP 
模块 的 create loc_conf 方 法 创建 1 组 结构 体 ， 用 于 存放 各 个 HITP 模 块 感 兴趣 的 loc 级 别 配置 


项 。 
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http 块 下 的 ngx_http _conf _ctx _+ 








某 server 块 下 的 ngx_http _conf _ctx _t 





该 server 所 属 的 某 个 location 
块 下 的 ngx_http _conf _ctx_t 


所 有 HTTP 模 块 create_loc _conf 产生 的 指针 


EE 


第 2 个 HTTP 模块 存储 
loc 级 别 配 置 、 由 


create _loc _conf 分 配 
的 结构 体 





图 4-3 location 块 与 http 块 、server 块 下 分 配 的 内 存 关 系 


这 个 事实 告诉 我 们 ， 在 nginx.conf 丁 置 文 件 中 http{}、server{}、location{} 块 的 忆 个 数 有 
多 少 ， 我 们 开发 的 HTTP 模 块 中 create loc conf 方 法 (如 果实 现 的 话 )〉 就 会 被 调用 多 少 次 ; 
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http{}、server{} 块 的 总 个 数 有 和 多少 ，create_srv_conf 方 法 (如 果实 现 的 话 ) 就 会 被 调用 多 少 
次 ;由 于 只 有 一 个 http{}， 所 以 create_ main conf 方 法 只 会 被 调用 一 次 。 这 3 个 方法 每 被 调用 一 
次 ， 就 会 生成 一 个 结构 体 ，Nginx 的 HTTP 框 染 居 然 创 建 了 如 此 多 的 结构 体 来 存放 配置 项 ， 怎 
样 理 解 呢 ? 很 简单 ， 就 是 为 了 解决 同名 配置 项 的 合并 问题 。 











如 果实 现 了 create main conf 方 法 ， 它 所 创建 的 结构 体 只 会 存放 直接 出 现在 http 介 块 下 的 


配置 项 ， 那 么 create main conf 只 会 被 调用 一 次 。 





如 果实 现 了 create_srv_con{ 方 法 ， 那 么 它 所 创建 的 结构 体 既 会 存放 直接 出 现在 http{} 抉 下 
的 配置 项 ， 也 会 存放 直接 出 现在 server{} 块 下 的 配置 项 。 为 什么 呢 ? 这 其 实 是 HTTP 框 架 的 一 
种 优秀 设计 。 例 如 ， 虽 然 某 个 配置 项 是 针对 于 server 虚 拟 主机 才 生 效 的 ， 但 http{} 下 面 可 能 
多 个 server{} 块 ， 对 于 用 户 来 说 ， 如 果 希 望 在 http{} 下 面 写 入 了 这 个 配置 项 后 对 所 有 的 
server{} 块 都 生效 ， 这 应 当 是 允许 的 ， 因 为 它 减少 了 用 户 的 工作 量 。 而 对 于 HTTP 框 架 而 言 ， 
就 需要 在 解析 直属 于 http{} 块 内 的 配置 项 时 ， 调 用 create_srv_conf 方 法 产生 一 个 结构 体 存放 配 
置 ， 解 析 到 一 个 serverf]} 块 时 再 调用 create srv conf 方 法 产生 一 个 结构 体 存 放 配置 ， 最 后 通过 
把 这 两 个 结构 体 合并 解决 两 个 问题 ， 有 一 个 配置 项 在 httpf} 块 内 出 现 了 ， 在 server 们 块 内 却 没 
有 出 现 ， 这 时 以 http 抉 内 的 配置 项 为 准 ， 可 如 果 这 个 配置 项 同时 在 http{} 块 、server{ 块 内 出 
现 了 ， 它 们 的 值 又 不 一 样 ， 此 时 应 当 由 对 它 感 兴 趣 的 HTTP 模 块 来 决定 配置 项 以 哪个 为 准 。 











如 果实 现 了 create_loc_conf 方 法 ， 那 么 它 所 创建 的 结构 体 将 会 出 现在 http{} 、server{}、 
location{} 块 中 ， 理 由 同上 。 这 是 一 种 非常 人 性 化 的 设计 ， 充 分 考虑 到 nginx.conf 文 件 中 高 级 
别 的 配置 可 以 对 所 包含 的 低级 别 配置 起 作用 ， 同 时 也 给 出 了 不 同 级 别 下 同名 配置 项 冲突 时 的 
解决 方案 《可 以 由 HTTP 模 块 自行 决定 其 行为 )。4.3.3 节 中 将 讨论 HTTP 框 架 如 何 合并 可 能 
现 的 冲突 配置 项 。 在 10.2 节 会 详细 讨论 HTTP 框 架 怎 样 管理 HTTP 模 块 产生 的 如 此 多 的 结构 
体 ， 以 及 每 个 HTTP 模 块 在 处 理 请 求 时 ，HTTP 框 架 又 是 怎样 把 正确 的 配置 结构 体 告诉 它 的 。 








4.3.3 ”如 何 合并 配置 项 
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在 4.3.1 节 描述 的 http 配 置 项 处 理 序列 图 (图 4-1〉 中 可 以 看 到 ， 在 第 20 步 ，HTTP 框 架 开 
始 合 并 http{} 、server{}、location{} 不 同 块 下 各 HTTP 模 块 生 成 的 存放 配置 项 的 结构 体 ， 那 么 
合并 配置 的 流程 是 怎样 进行 的 呢 ? 本 世 将 简单 介绍 这 一 工作 流程 ， 而 在 10.2.4 市 中 会 利用 源 
代码 完整 地 说 明 它 。 


图 4-4 是 合并 配置 项 过 程 的 活动 图 ， 它 主要 包含 四 大 部 分 内 容 。 


. 如 果 HTIP 模 块 实现 了 merge_srv_conf 方 法 ， 就 将 http{...} 块 下 create_strv_conf 生 成 的 结构 


体 与 遍历 每 一 个 server{...} 配置 块 下 的 结构 体 做 merge_strv_conf 操 作 。 


. 如 果 HTIP 模 块 实现 了 merge_loc_conf 方 法 ， 就 将 http{...} 块 下 create_loc_conf 生 成 的 结构 


体 与 谱 套 的 每 一 个 server{.….} 配置 块 下 生成 的 结构 体 做 merge_loc_conf 操 作 。 


. 如 果 HTIP 模 块 实现 了 merge_loc_conf 方 法 ， 就 将 server{...} 块 下 create_loc_conf 生 成 的 结 
构 体 与 识 套 的 每 一 个 location{...} 配 置 块 下 create_loc_conf 生 成 的 数据 结构 做 merge_loc_conf 操 
作 。 


. 如 果 HTIP 模 块 实现 了 merge_loc_conf 方 法 ， 就 将 location{...} 块 下 create_loc_conf 生 成 的 
结构 体 与 继续 谱 套 的 每 一 个 location{...} 配置 块 下 create_loc_conf 生 成 的 数据 结构 做 
merge_loc_conf 操 作 。 注 意 ， 这 个 动作 会 无 限 地 递归 下 去 ， 也 就 是 说 ，location 配 置 块 内 继续 
庶 套 location， 而 诬 套 多 少 层 在 本 节 中 是 不 受 HTTP 框 架 限制 的 。 不 过 在 图 4-4 没 有 表达 出 无 限 
地 递归 处 理 艇 套 location 块 的 意思 ， 仅 以 location 中 再 识 套 一 个 location 作 为 例子 简单 说 明 一 
Ty 
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依 序 遍历 所 有 的 HTTP 模 块 






[获取 将 要 执行 合并 配置 项 的 HTTP 模块 ] 


[已 经 处 理 完 所 有 HTTP 模 块 ] 





[遍历 到 一 个 HTTP 模块 ] 






[遍历 完 所 有 的 server 块 
遍历 当前 HTTP 模 块 在 所 有 server 块 下 生成 的 结构 体 


[获取 该 HTTP 模 块 在 所 有 server 块 下 生成 的 结构 体 ] 


[获取 到 某 个 server 块 下 生成 的 结构 体 ] 


[ 如 果实 现 了 merge_srv _conf 方法 ] 
[没有 实现 merge_loc _conf ] [merge_srv _conf 方法 没有 实现 ] 


用 merge_srv _conf 合并 http 块 、server 块 下 create _srv _conf 产生 的 结构 体 


[是 和 否 实 现 merge_loc _conf 方法 ] 


[遍历 完 所 有 的 location 块 ] 
[如 果实 现 了 merge_loc _conf 方法 ] 


用 merge_loc _conf 合并 http 块 、server 块 下 create _loc _conf 方法 产生 的 结构 体 







遍历 该 server 块 下 艇 套 的 所 有 location 块 生 成 的 结构 体 






[获取 该 HTTP 模块 在 所 有 location 块 下 生成 的 结构 体 ] 





[获取 到 location 块 ] 






用 merge_loc _conf 合并 server 块 、location 块 下 create_loc _conf 产生 的 结构 体 








遍历 完 所 有 的 子 location 块 ] 
遍历 在 该 location 块 再 次 嵌 套 的 所 有 location 块 下 生成 的 结构 体 
[获取 location 下 赃 套 的 location 抉 ] 










[获取 到 子 location 块 ] 
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图 44 解析 完 所 有 http 配 置 项 后 合并 配置 的 流程 图 





图 4-4 包 括 4 重 循环 ， 第 1 层 〈 最 外 层 ) 遇 历 所 有 的 HTTP 模块 ， 第 2 层 通 历 所 有 的 
server{..} 配 置 块 ， 第 3 层 是 过 历 茶 个 server 全 块 中 和 藤 套 的 所 有 1location{..} 块 ， 第 4 层 过 历 茶 个 
location{} 块 中 继续 巷 套 的 所 有 location 块 《实际 上 ， 它 会 一 直 递 归 下 去 以 解析 可 能 被 层 层 竺 
套 的 location 块 ， 详 见 10.2 节 ) 。 读 者 可 以 对 照 上 述 4 重 循环 来 理解 合并 配置 项 的 流程 图 。 











4.3.4 预 设 配置 项 处 理 方法 的 工作 原理 


在 4.2.4 节 中 可 以 看 到 ， 目 定义 的 配置 项 处 理 方法 读 取 参数 值 也 是 很 简单 的 ， 直 接 使 用 
ngx_str_t#svalue=cf->args->elfs; 就 可 以 获取 参数 。 接 下 来 将 把 参数 赋值 到 ngx_http mytest conf { 
结构 体 的 相应 成 员 中 。 不 过 ， 预 设 的 配置 项 处 理 方法 并 不 知道 每 个 HTTP 模 块 所 定义 的 结构 
体 包 括 哪 些 成 员 ， 那 么 ， 它 们 怎么 可 以 做 到 具有 通用 性 的 呢 ? 





很 简单 ， 返 回 到 4.2.2 节 就 可 以 看 到 ，ngx_command t 结 构 体 的 offset 成 员 已 经 进行 了 正确 
的 设置 (实际 存储 参数 的 成 员 相 对 于 整个 结构 体 的 偏 移 位 置 ) ，Nginx 配 置 项 解析 模块 在 调 
用 ngx_command t 结 构 体 的 set 回 调 方法 时 ， 会 同时 把 offset 偏 移 位 置 传 进来 。 每 种 预 设 的 配置 
项 解析 方法 都 只 解析 特定 的 数据 结构 ， 也 就 是 说 ， 它 们 既 知 道 存 储 参 数 的 成 员 相 对 于 整个 结 
构 体 的 侦 移 量 ， 又 知道 这 个 成 员 的 数据 类 型 ， 目 然 可 以 做 到 具有 通用 性 了 。 


下 面 以 读 取 数字 配置 项 的 方法 ngx_conf set num slot 为 例 ， 说 明 预 设 的 14 个 通用 方法 是 
如 何 解 析 配 置 项 的 。 





char ngx conf set num slot (ngx conf t cf, ngx command 七 cma void conf) 





// 指针 


Conf 就 是 存储 参数 的 结构 体 的 地 址 


char p = conf; 
ngx int t np; 
ngx_ str 七 value; 
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/* 根 据 


ngx command 七 中 的 


offset 偏 移 量 ， 可 以 找到 结构 体 中 的 成 员 ， 而 对 于 


ngx conf set num slot 方 法 而 言 ， 存 储 数 字 的 必须 是 





ngx int 七 类 型 


np = (ngx int t ) (p + cmd->offset); 
/* 在 这 里 可 以 知道 为 什么 要 把 使 用 


ngx conf set num slot 方 法 解析 的 成 员 在 





create loc conf 等 方法 中 初始 化 为 


NGX_CONF_UNSET， 否 则 是 会 报错 的 





if (np != NGX CONF UNSET) { 
return "is duplicate"; 





} 
// value 将 指向 配置 项 的 参数 


Value = cf->args->elts; 
/* 将 字符 串 的 参数 转化 为 整 型 ， 并 设置 到 


create loc conf 等 方法 生成 的 结构 体 的 相关 成 员 上 


np = ngx atoi (value[1] .data, value[1] .len); 
if (*np == NGX ERROR) { 
return "invalid number"; 





} 
// 如 果 


ngx command 七 中 的 


Post 已 经 实现 ， 那 么 还 需要 调用 


post->post handler 方 法 


if (cmd->post) { 

post = cmd->post; 

return post->post handler (cf, post, np); 
} 
return NGX CONF OR; 





可 以 看 到 ， 这 是 一 种 非常 灵活 和 巧妙 的 设计 。 
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4.4 error 日志 的 用 法 


Nginx 的 日 志 模 块 ( 这 里 所 说 的 日 志 模 块 是 ngx_errlog_ module 模 块 ， 而 
ngx_http_ log module 模 块 是 用 于 记录 HITP 请 求 的 访问 日 志 的， 两 者 功能 不 同 ， 在 实现 上 也 没 
有 任何 关系 ) 为 其 他 模块 提供 了 基本 的 记录 日 志 功 能 ， 本 章 提 到 的 mytest 模 块 当 然 也 可 以 使 
用 日 志 模 块 提 供 的 接口 。 出 于 跨 平台 的 考虑 ， 日 志 模 块 提 供 了 相当 多 的 接口 ， 主 要 是 因为 有 
些 平台 下 不 文 持 可 变 参 数 。 本 节 主 要 讨论 文 持 可 变 参数 的 日 志 接 口 ， 事 实 上 不 文 持 可 变 参数 
的 日 志 接 口 在 实现 方面 与 其 并 没有 太 大 的 不 同 (参见 表 4-9) 。 首 先 看 一 下 日 志 模 块 对 于 文 
持 可 变 参 数 平台 而 提供 的 3 个 接口 。 














#define ngx log error(level, log, args...) \ 
if ((1og)->1og level >= level) ngx 1og error core(level, log, args) 
#define ngx log debug(level, log, args...) 
if ((10g)->log level & level) \ 
ngx_ log error core(NGX LOG DEBUG, log, args) 
void ngx log error core(ngx uint t level, ngx log t log, ngx err t err const char fmt, ...); 














Nginx 的 日 志 模 块 记录 日 志 的 核心 功能 是 由 ngx_log_error_core 方 法 实现 的 ，ngx_log error 
宏和 ngx log debug 宏 只 是 对 它 做 了 简单 的 封装 ， 一 般 情 况 下 记录 日 志 时 只 需要 使 用 这 两 个 








注 


ngx_log error 宏 和 ngx_log debug 宏 都 包括 参数 level、log、err、fmt， 下 面 分 别 解 释 这 4 个 
参数 的 意义 。 


(1) level 参 数 
对 于 ngx_log error 宏 来 说 ，level 表 示 当 前 这 条 日 志 的 级 别 。 它 的 取 值 疙 围 见 表 4-6。 


表 4-6 ngx_log_error 日 志 接 口 level 参 数 的 取 值 范围 
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级 别名 称 


Te 


NGX LOG STDERR 


NGX LOG EMERG 


级 别名 称 
NGX LOG ALERT 
NGX LOG CRIT 
NGX LOG ERR 
NGX LOG WARN 
NGX LOG NOTICE 
NGX_LOG INFO 
NGX LOG DEBUG 


> 


最 高 级 别 日 志 ， 日 志 的 内 容 不 会 再 写 入 log 参数 指定 的 文件 ， 而 是 会 直接 将 
日 志 输 出 到 标准 错误 设备 ， 如 控制 台 屏 幕 

大 于 NGX _ LOG _ALERT 级 别 ， 而 小 于 或 等 于 NGX_LOG EMERG 级 别 的 
日 志 都 会 输出 到 log 参数 指定 的 文件 中 


大 于 NGX_LOG _CRIT 级 别 

大 于 NGX LOG ERR 级别 

大 于 NGX _ LOG _WARN 级 别 
大 于 NGX LOG NOTICE 级 别 
大 于 NGX _ LOG INFO 级 别 

大 于 NGX _ LOG DEBUG 级 别 


调试 级 别 ， 最 低级 别 日 志 








使 用 ngx_log error 宏 记录 日 志 时 ， 如 果 传 入 的 level 级 别 小 于 或 等 于 log 参 数 中 的 日 志 级 别 
(通常 是 由 nginx.conf 配 置 文 件 中 指定 )， 就 会 输出 日 志 内 容 ， 人 否则 这 条 日 志 会 被 忽略 。 


在 使 用 ngx log_debug 宏 时 ，level 的 意义 完全 不 同 ， 它 表达 的 意义 不 再 是 级 别 (已经 是 
DEBUG 级 别 ) ， 而 是 日 志 类 型 ， 因 为 ngx log debug 宏 记录 的 日 志 必 须 是 NGX LOG DEBUG 
调试 级 别 的 ， 这 里 的 level 由 各 子 模块 定义 。level 的 取 值 范围 参见 表 4-7。 


表 4-7 hpx_log _ debug 上 日志 接口 level 参 数 的 取 值 范围 


级 别名 称 
NGX LOG DEBUG CORE 
NGX LOG DEBUG ALLOC 
NGX LOG DEBUG MUTEX 
NGX_LOG DEBUG EVENT 
NGX LOG DEBUG HTTP 
NGX LOG DEBUG MAIL 
NGX LOG DEBUG MYSQL 








Nginx 核心 模块 的 调试 日 志 

Nginx 在 分 配 内 存 时 使 用 的 调试 日 志 

Nginx 在 使 用 进程 锁 时 使 用 的 调试 日 志 

Nginx 事件 模块 的 调试 日 志 

Nginx http 模块 的 调试 日 志 

Nginx 邮件 模块 的 调试 日 志 

表示 与 MySQL 相关 的 Nginx 模块 所 使 用 的 调试 日 志 





当 HTTP 模 块 调用 ngx log_debug 宏 记录 日 志 时 ， 传 入 的 level 参 数 是 
NGX_LOG DEBUG HTTP， 这 时 如 果 log 参 数 不 属 于 HTTP 模 块 ， 如 使 用 了 event 事 件 模 块 的 
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log， 则 不 会 输出 任何 日 志 。 它 正 是 ngx log debug 拥 有 level 参 数 的 意义 所 在 。 
(2) log 人 参数 


实际 上 ， 在 开发 HTTP 模 块 时 我 们 并 不 用 关心 log 参 数 的 构造 ， 因 为 在 处 理 请 求 时 
ngx_http_request_t 结 构 中 的 connection 成 员 就 有 一 个 ngx_log {类 型 的 log 成 员 ， 可 以 传 给 
ngx log error 宏 和 ngx_log debug 宏 记录 日 志 。 在 读 取 配置 阶段 ，ngx_conf t 结 构 也 有 log 成 员 可 
以 用 来 记录 日 志 〔 读 取 配 置 阶段 时 的 日 志 信 息 都 将 输出 到 控制 台 屏 秦 ) 。 下 面 简单 地 看 一 下 
ngx log t 的 定义 。 











typedef struct ngx log s ngx log t; 
typedef u char (ngx log handler pt) (ngx log t log, uu char buf, size t len); 
struct ngx log s 1 


// 日 志 级 别 或 者 日 志 类 型 





ngx uint t log level; 


// 日 志文 件 


ngx open file t *file; 


// 连接 数 ， 不 为 


0 时 会 输出 到 日 志 中 


ngx atomic uint 七 connection; 


/* 记 录 日 志 时 的 回调 方法 。 当 


handler 已 经 实现 (不 为 


NULL) ， 并 且 不 是 





DEBUG 调 试 级 别 时 ， 才 会 调用 





handler 钧 子 方法 


ngx log handler pt handler; 
每 个 模块 都 可 以 自 定义 


data 的 使 用 方法 。 通 常 ， 


data 参 数 都 是 在 实现 了 上 面 的 
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HTTP 框 架 就 定义 了 


handler 方 法 ， 并 在 


data 中 放 入 了 这 个 请 求 的 上 下 文 信息 ， 这 样 每 次 输出 日 志 时 都 会 把 这 个 请 求 


URI 输 出 到 日 志 的 尾部 


* 

void data; 

/* 表 示 当 前 的 动作 。 实 际 上 ， 
action 与 


data 是 一 样 的 ， 只 有 在 实现 了 


handler 回 调 方 法 后 才 会 使 用 。 例 如 ， 


HTTP 框 架 就 在 


handler 方 法 中 检查 


action 是 否 为 


NUL + 如 果 不 为 











NULL， 就 会 在 日 志 后 加 入 “ 





while ” 


+action， 以 此 表示 当前 日 志 是 在 进行 什么 操作 ， 帮 助 定位 问题 


# 
char action; 


}; 








可 以 看 到 ， 如 果 只 是 想 把 相应 的 信息 记录 到 日 志文 件 中 ， 那 么 完全 不 需要 关心 ngx_log t 
类 型 的 log 参 数 是 如 何 构 造 的 。 特 别 是 在 编写 HTTP 模 块 时 ，HTTP 框 架 要 求 所 有 的 HTTP 模 块 
都 使 用 它 提供 的 log， 如 末 重 定义 ngx_log t 中 的 handler 方 法 ， 或 者 修改 data 指 癌 的 地 址 ， 那 么 
很 可 能 会 造成 一 系列 问题 。 


然而 ， 从 上 文 对 ngx log t 结 构 的 描述 中 可 以 看 出 ， 如 果 定 义 一 种 新 的 模块 (不 是 HTTP 
模块 ) ， 那 么 日 志 模 块 提 供 很 强大 的 功能 ， 可 以 把 一 些 通 用 化 的 工作 都 放 到 handler 回 调 方法 
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中 实现 。 
(3) err 参 数 


err 参 数 束 是 错误 码 ， 一 般 古 执行 系统 调用 失败 后 取得 的 errno 参 数 。 当 err 不 为 0 时 ， 


Nginx 日 志 模 块 将 会 在 正常 日 志 内 容 前 输出 这 个 错误 码 以 及 其 对 应 的 字符 串 形式 的 错误 消 
自 


yo 





(4) fimt 参 数 


fmt 就 是 可 变 参数 ， 就 像 在 printf 等 C 语 言 方 法 中 的 输入 一 样 。 例 如 : 





ngx log error (NGX LOG ALERT, r->connection->log,0, 
"test flag=%d,test str=%V,path=%*s,mycf addr=%p", 
mycf->my flag, 
&mycft->my _ str, 
mycf->my path->name.len, 
mycf->my path->name.data, 
mycf); 








fmt 的 大 部 分 规则 与 printt 等 通用 可 变 参数 是 一 致 的 ， 然 而 Nginx 为 了 方便 它 自 定义 的 数据 
类 型 ， 重 新 实现 了 基本 的 ngx_vslprintf 方 法 。 例 如 ， 增 加 了 诸如 %VY 等 这 样 的 转换 类 型 ，%V 
后 可 加 ngx_str_t 尖 型 的 变量 ， 这 些 都 是 普通 的 printft 中 没有 的 。 表 4-8 列 出 了 ngx_vslprintf 中 支 
持 的 27 种 转换 格式 。 


er 注意 ptintf 或 者 sptintf 支 持 的 一 些 转换 格式 在 npx_vslptintf 中 是 不 支持 的 ， 或 者 意义 
不 同 。 


表 4.8 打印 日 志 或 者 使 用 ngx_sprintf 系 列 方法 转换 字符 串 时 支持 的 27 种 转化 格式 
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转换 格式 
%ou 


Vom 


SoX 


ox 


%. 


%f 


00 从 


05 


%oV 


0v 


%O 
%P 
%oT 
SoM 
Voz 
%oi 
%od 
%6l 
9%D 
9%6L 


oA 
Yor 


?op 
oc 
%o7. 
oN 


Vo%o 


用 法 

表示 无 符号 ， 其 后 还 可 以 跟 其 他 转换 符号 ， 如 %ui 表示 要 转换 的 类 型 是 ngx_uint t。 如 果 其 后 没有 
跟 转 换 符 号 ， 则 表示 要 转换 的 类 型 是 无 符号 十 进 制 正 数 

表示 以 最 大 长 度 来 转换 数字 类 塌 (如 int) 

以 十 六 进 制 来 格式 化 转换 后 的 数据 ， 注意，Nginx 中 的 %X 与 printf 等 转换 格式 完全 不 同 ， 它 只 是 
限制 转换 后 的 数字 以 十 六 进 制 格式 来 显示 ， 而 不 是 限制 相应 参数 的 类 型 。 人 例如, %Xd 后 跟着 int 类 型 ， 
表示 以 十 六 进 制 格式 来 显示 int 整数 ， 而 %Xp 表示 以 十 六 进 制 格式 来 显示 指针 地 址 。 如 果 仅 有 %X， 
那么 是 设 有 任何 输出 的 

%x 与 %X 的 用 法 完全 相同 ， 只 是 %X 以 A、B、C、D、E、F 表示 十 进 制 中 的 10、L1、12、13、 
14、15， 而 %x 是 以 小 写 的 a、b、c、d、e、 了 来 表示 

其 后 必须 紧 跟 数字 - 当前 实现 版 本 下 必须 与 %f 配合 使 用 ， 表 示 转 换 淫 点数 时 小 数 部 分 的 位 数 。 例 
如 ，%.10f 表示 转换 double 类 型 时 ， 小 数 点 后 转换 且 必 须 转换 为 10 位 ， 不足 10 位 以 0 填补 

转换 double 类 型 数据 。 注 意 ， 它 与 printf 等 标准 C 语 盲 中 的 %f 完 全 不 同 ， 如 果 想 转换 小 数 部 分 ， 
则 必须 加 上 %.(numberjf。 参 见 本 表 中 %. 的 描述 

表示 要 转换 的 字符 长 度 。 目 前 仅 与 %s 配合 使 用 

转换 1 个 char* 或 者 u_char* 的 字符 串 。 与 %# 配合 使 用 时 ，%*s 才 示 和 输出 指定 长 度 的 字符 串 ， 基 
后 必须 有 两 个 参数 : 表示 输出 字符 串 长 度 的 size t 和 字符 串 地 址 char* 类 型 。 如 果 不 与 %* 配合 使 用 ， 
而 与 printf 等 标准 格式 相同 ， 那 么 字符 吾 必 须 以 “\0 ”结尾 

转换 ngx_str 类 型 ，%V 对 应 的 参数 必须 是 ngx_str1 变 量 的 地 址 。 它 将 会 按照 ngx str t 类 型 的 
len 长 度 来 输出 data 字符 串 

转换 ngx_variable_value t 类 型 。%v 对 应 的 参数 必须 是 ngx_variable_value_ 【变量 的 地 址 。 它 将 会 按 
腿 ngx_variable_value t 类 型 的 len 长 度 来 输出 data 字符 串 

转换 1 个 o 企 1 类 型 

转换 1 个 ngx_pid +t 类 再 

转换 1 个 time 1 类 现 

转换 1 个 ngx_msec {类 型 

转换 ssize 【类型 数据 ， 如 果 用 %uz， 则 转换 的 数据 类 型 是 size 1 

转换 ngx_int t 型 数据 ， 如 果 用 %ui， 则 转换 的 数据 类 型 是 ngx_uint 1 

转换 int 型 数据 ， 如 果 用 %ud， 则 转换 的 数据 类 卉 是 u int 

转换 long 型 数据 ， 如 果 用 %ul， 则 转换 的 数据 类 型 是 u_long 

转换 int32 1 型 数据 ， 如 果 用 %uD， 则 转换 的 数据 类 型 是 uint32 1 

转换 int64 上 型 数据 ， 如 果 用 %uL ， 则 转 搞 的 数据 类 型 是 uint64 + 

转换 ngx_atomic _ int t 击 数 据 ， 如 此 用 %uA， 则 转换 的 数据 类 型 是 ngx_atomic uint t 

转换 1 个 rlim t 类 卉 。 系统 调用 getrlimit 或 者 setrlimit 时 都 会 使 用 rlim t 类 型 参数 ， 它 实际 上 是 一 
个 算术 数据 类 型 ， 等 同 于 类 型 int、size 或 者 ofF 1 

转换 1 个 指针 (地 址 ) 

转换 1 个 字符 类 型 

表示 \0' 

表示 "Wn' 换行 符 ， 即 Wx0a"， 在 windows 操作 系统 上 则 表示 "rin'， 也 就 是 x0d\x0a" 

打印 1 个 百 分 写 (%) 


例如 ， 在 4.2.4 节 自 定义 的 ngx conf set myconfig 方 法 中 ， 可 以 这 样 输出 日 志 。 


D: // WAN ThUXxprope. CoOn 





long tl = 490 
u long tul = 
irit32 七 二 工 32 
ngx_str t 
double tdoub 
int x = 15; 


ngx_ log error (NGX LOG ALERT, cf->1log, 


0000000; 
5000000000; 
= 110; 

七 写 七 全 三 
= 3.1415926535897932; 





ngx string("teststr"); 


"1=%1,ul=%ul,D=%D, p=%p, f=%.10f, str=%V, x=%xd, X=%Xd", 





tl;tulyti32, ti32;tdoub,Ststr;xyx)}; 





上 述 这 段 代 人 码 将 会 输出 : 





nginx: [alert 


] 1=4900000000,ul=5000000000,D=110,p=00007FFFF26B36DC, f=3.1415926536, str=teststr,x=f,X=F 





在 Nginx 的 许多 核心 模块 中 可 以 看 到 ， 它 们 多 使 用 的 是 debug 调 试 级 别 的 日 志 接 口 ， 见 表 


4-9。 


日 志 接 口 
ngx log debug0 
ngx log debugl 
nex log _ debusg2 
ngx log debug3 
ngx log debug4 
ngx log debueg5 
ngx log debug6 


negx log debug7 


ngx log debug8 


表 4-9 Nginx 提 供 的 不 支持 可 变 参 数 的 调试 日 志 接 口 


fmt 格式 后 不 接受 参 炎 


fmt 格式 后 只 

fmt 格式 后 

fmt 格式 后 只 接受 
fmt 格式 后 只 接受 
fmt 格式 后 只 接受 
fmt 格式 后 只 接受 6 
fmt 格式 后 只 接受 7 


fmt 格式 后 只 接受 8- 





ngx log debugO(level. 
ngx log debugl(level. 
ngx log debug2(level. 
ngx log debug3(level. 
ngx log debug4(level. 
ngx log debug5 (level. 


ngx log debug6(level. 


» eIT， 


fmt., argl, arg2， 


, argl, arg2. 


ngex log debug7(level, log. em fmt argl, arg2, arg3, arg4. arg5, arg6, arg7) 


ngx_ log debug8(level. log, err, fmt., argl, arg2, arg3, arg4. arg5, arg6, 


arg7. arg8) 
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4.5 人 请求 的 上 下 文 


在 Nginx 中 ， 上 下 文 有 很 多 种 含义 ， 然 而 本 节 描 述 的 上 下 文 是 指 HITTP 框 架 为 每 个 HTTP 
请 求 所 准备 的 结构 体 。HTTP 框 架 定 义 的 这 个 上 下 文 是 针对 于 HTTP 请 求 的 ， 而 且 一 个 HTTP 
请 求 对 应 于 每 一 个 HTTP 模 块 都 可 以 有 一 个 独立 的 上 下 文 结构 体 ( 并 不 是 一 个 请 求 的 上 下 文 
由 所 有 HTTP 模 块 共用 ) 。 





4.5.1] 上 下 文 与 全 异步 Web 服 务 器 的 关系 


上 上 下文 是 什么 ? 简单 地 讲 ， 就 是 在 一 个 请 求 的 处 理 过 程 中 ， 用 类 似 struct 这 样 的 结构 体 把 
一 些 关 键 的 信息 都 保存 下 来 ， 这 个 结构 体 可 以 称 为 请 求 的 上 下 文 。 每 个 HTTP 模 块 都 可 以 有 
自己 的 上 下 文 结构 体 ， 一 般 都 是 在 刚 开 始 处 理 请 求 时 在 内 存 池 上 分 配 它 ， 之 后 当 经 由 epoll、 
HTTP 框 架 再 次 调用 到 HITTP 模 块 的 处 理 方法 时 ， 这 个 HITP 模 块 可 以 由 请 求 的 上 下 文 结构 体 
中 获取 信息 。 请 求 结 束 时 就 会 销毁 该 请 求 的 内 存 池 ， 目 然 也 就 销毁 了 上 下 文 结构 体 。 以 上 惑 
是 HTTP 请 求 上 下 文 的 使 用 场景 ， 由 于 1 个 上 下 文 结构 体 是 仅 对 1 个 请 求 1 个 模块 而 言 的 ， 所 以 
它 是 低 耦 合 的 。 如 果 这 个 模块 不 需要 使 用 上 下 文 ， 也 可 以 完全 不 理会 HITP 上 下 文 这 个 概 
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那么 ， 为 什么 要 定义 HITP 上 下 文 这 个 概念 呢 ? 因为 Nginx 是 个 强大 的 全 异步 处 理 的 Web 
服务 器 ， 意 味 着 1 个 请 求 并 不 会 在 epoll 的 1 次 调度 中 处 理 完成 ， 甚 至 可 能 成 干 上 万 次 的 调度 各 
个 HTTP 模 块 后 才能 完成 请 求 的 处 理 。 











怎么 理解 上 面 这 句 话 呢 ?以 Apache 服 务 器 为 例 ，Apache 就 像 某 些 高 档 餐 厅 ， 每 位 客人 
CHTTP 请 求 ) 都 有 1 位 服务 员 〔〈 一 个 Apache 进 程 ) 全 程 服务 ， 每 位 服务 员 只 有 从 头 至 尾 服务 
完 这 位 客人 后 ， 才 能 去 为 下 一 个 客人 提供 服务 。 因 此 餐厅 的 并 发 处 理 数量 受制 于 服务 员 的 数 
量 ， 但 服务 员 的 数量 也 不 是 越 多 越 好 ， 因 为 餐厅 的 固定 设施 〈CPU) 是 有 限 的 ， 它 的 管理 成 
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本 《〈Linux 内 核 的 进程 切换 成 本 ) 也 会 随 着 服务 员 数 量 的 增加 而 提高 ， 最 终 影响 服务 质量 。 
Nginx 则 不 同 ， 它 束 像 Playfirst 公 司 在 2005 年 及 布 的 休闲 游戏 《美女 餐厅 》 一 样 ，1 位 服务 员 
同时 处 理 押 有 客人 的 需求 。 当 1 位 客人 进入 餐厅 后 ， 服 务 员 首先 给 它 安 排 好 桌子 并 把 沫 单 给 
客人 后 就 离开 了 ， 继 续 服 务 于 其 他 客人 。 当 这 位 客人 决定 点 哪些 沫 后 ， 就 试图 去 叫 服 务 员 过 
来 处 理 点 染 和 需求， 当然， 服务 员 可 能 正在 忙于 其 他 客人 ， 但 只 要 一 有 空闲 就 会 过 来 拿 菜 单 并 
交 给 厨房 ， 再 去 服务 于 其 他 客人 。 直 到 厨房 通知 这 位 客人 的 沫 已 页 饪 完毕 ， 服 务 员 再 取 来 亲 
主动 地 传递 给 客人 ， 请 他 用 餐 ， 之 后 服务 员 又 去 寻找 是 否 有 其 他 客人 在 等 竺 服务 。 














可 以 注意 到 ， 当 1 位 客人 进入 Nginx“ 和 餐厅 ”时 ， 首 先是 由 客人 来 "激活 ?Nginx“ 服 务 员 ” 的 。 
Nginx“' 服 务 员 ” 再 次 来 处 理 这 位 客人 的 请 求 时 ， 有 可 能 是 因为 这 位 客人 点 完全 后 大 声 地 叫 
Nginx“ 服 务 员 ”， 等 候 她 来 服务 ， 也 有 可 能 是 因为 厨房 做 好 亲 后 厨师 “激活 ”了 这 位 客人 的 服 
务 ， 也 就 是 说 “激活 ?Nginx' 服 务 员 ” 的 对 象 是 不 辐 定 的 。 餐 厅 的 流程 是 先 点 菜 ， 再 上 沫 ， 最 后 
收 账单 以 及 撤 碗 盘 ， 但 客人 是 不 想 了 解 这 个 流程 的 ， 所 以 Nginx“ 服 务 员 ”需要 为 每 位 客人 建 
立 上 下 文 结构 体 来 表示 客人 进行 到 哪个 步骤 ， 即 他 点 了 哪些 菜 、 目 前 已 经 上 了 哪些 菜 ， 这 些 
言 思 都 需要 独立 的 保存 。“ 服 务 员 ”不 会 去 记 住 所 有 客人 的 “上 下 文 信 息 ”， 因 为 要 同时 服务 的 
客人 可 能 很 多 ， 只 有 在 服务 到 茶 位 客人 时 才 会 去 查 对 应 的 “上 下 文 信息 ”。 



































上 面 说 的 Nginx“ 服 务 员 ”就 像 Nginx worker 进 程 ， 客 人 就 是 一 个 个 请 求 ， 一 个 Nginx 进 程 同 
时 可 以 处 理 百 万 级 别 的 并 发 HTTP 请求。 厨房 这 些 设施 可 能 是 网 卡 、 硬 盘 等 硬件 。 因 此 ， 如 
果 我 们 开发 的 HTTP 模 块 会 多 次 反复 处 理 同 1 个 请 求 ， 那 么 必须 定义 上 下 文 结构 体 来 保存 处 理 
过 程 的 中 间 状 态 ， 因 为 谁 也 不 知道 下 一 次 是 由 网 卡 还 是 人 硬盘 等 服务 来 激活 Nginx 进 程 继续 处 
理 这 个 请 求 。Nginx 框 架 不 会 维护 这 个 上 下 文 ， 只 能 由 这 个 请 求 自己 保存 着 上 下 文 结构 体 。 














再 把 这 个 例子 对 应 到 HTTP 框 架 中 。 点 菜 可 能 是 一 件 非常 复杂 的 事 ， 因 为 可 能 涉及 凉 
菜 、 热 莱 、 汤 、 甜 品 等 。 假 如 HTTP 模 块 A 负责 凉 亲 、HTTP 模 块 B 负 责 热 菜 、HTTP 模 块 C 负 
责 疡 。 当 一 位 新 客人 到 来 后 ， 他 招呼 着 服务 员 〈worker 进 程 ) 和 HTTP 框 架 处 理 他 的 点 荣 需 
求 时 (假设 他 想 点 2 个 凉菜 、5 个 热 菜 、1 个 汤 ) ，HTTP 模 块 A 刚 处 理 了 1 个 凉菜 ， 又 有 其 他 客 
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人 将 服务 员 叫 走 了 ， 那 么 ， 这 个 客人 处 必须 有 一 张 纸 记录 着 关于 头 麻 刚 点 了 了 一个， 为 一 张 纸 
记录 着 热 菜 一 个 没 点 ， 由 于 HTTP 模 块 C 知 道 ， 当 前 的 餐厅 汤 已 经 卖 完 ， 业 务实 在 是 太 简单 了 
(回顾 一 下 第 3 章 的 helloword 例 子 )， 所 以 不 需要 再 有 一 张 纸 记录 着 汤 有 没有 把。 这 两 张 纸 
只 从 属于 这 个 客人 ， 对 于 其 他 客人 没有 意义 ， 这 就 是 上 面 所 说 的 ， 上 下 文 只 是 对 于 一 个 请 求 
而 言 。 同 时 ， 每 个 HTTP 模块 都 可 以 拥有 记录 客人 《请 求 ) 状态 的 纸 ， 这 张 纸 就 其 实 就 是 上 
下 文 结构 体 。 当 这 个 客人 叫 来 服务 员 时 ， 各 个 HTTP 模块 可 以 碍 看 客人 号 前 的 两 张 纸 ， 了 解 
到 点 了 哪些 荣 ， 这 才 可 以 继续 处 理 下 去 。 























在 第 3 章 中 的 例子 中 虽然 没有 使 用 到 上 下 文 ， 但 也 完成 了 许多 功能 ， 这 是 因为 第 3 章 中 的 
mytest 模 块 对 同 1 个 请 求 只 处 理 了 一 次 《发 送 啊 应 包 时 虽然 有 许多 次 调用 ， 但 这 些 调 用 是 由 
HTTP 框 染 帮 助 我 们 完成 的 ， 并 没有 再 次 回调 mytest 模 块 中 的 方法 ) ， 它 的 功能 非常 简单 。 在 
第 $ 章 中 可 以 看 到 ， 无 论 是 subrequest 还 是 upstream， 都 必须 有 上 下 文 结构 体 来 支持 异步 地 访 
问 第 三 方 服务 。 








4.5.2 ”如 何 使 用 HITP 上 下 文 


ngx_http_get module_ctx 和 和 ngx_http_set_ctx 这 两 个 宏 可 以 完成 HTTP 上 下 文 的 设置 和 使 用 。 
先 看 看 这 两 个 宏 的 定义 ， 如 下 所 示 。 





#define ngx http get module ctx(r, module) (r)->ctx[module.ctx index] 
#define ngx http set ctx(r, c¢, module) r->ctx[module.ctx index] = c; 








ngx_http_get_module_ctx 接 受 两 个 参数 ， 其 中 第 1 个 参数 是 ngx_http_request t 指 针 ， 第 2 个 
参数 则 是 当前 的 HTTP 模 块 对 象 。 例 如 ， 在 mytest 模 块 中 使 用 的 就 是 在 3.5 节 中 定义 的 
ngx_module t 类 型 的 ngx_http_mytest_module 结 构 体 。ngx_http_get_module_ctx 返 回 值 就 是 某 个 
HTTP 模 块 的 上 下 文 结构 体 指针 ， 如 果 这 个 HTTP 模 块 没有 设置 过 上 下 文 ， 那 么 将 会 返回 
NULL 空 指针 。 因 此 ， 在 任何 一 个 HTTP 模 块 中 ， 都 可 以 使 用 ngx_http_get_module_ctx 获 取 所 有 
HTTP 模 块 为 该 请 求 创建 的 上 下 文 结构 体 。 
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ngx_http_set_ctx 接 受 3 个 参数 ， 其 中 第 1 个 参数 是 ngx_http_request t 指 针 ， 第 2 个 参数 是 准 
备 设置 的 上 下 文 结构 体 的 指针 ， 第 3 个 参数 则 是 HTTP 模 块 对 象 。 


举 个 简单 的 例子 来 说 明 如 何 使 用 ngx http_get module_ctx 宏 和 ngx http set ctx 宏 。 首 先 建 
Ymytest 模 块 的 上 下 文 结构 体 ， 如 ngx_http_mytest_ctx t。 





typedef struct { 
ngx uint t my step; 
} ngx http mytest ctx t; 








当 请 求 第 1 次 进入 mytest 模 块 处 理 时 ， 创 建 ngx_http_mytest_ctx t 结 构 体 ， 并 设置 到 这 个 请 
求 的 上 下 文中 。 





static ngx int 七 
ngx http mytest handler (ngx http request t *r) 
{ 

// 首先 调用 


ngx http get module ctx 宏 来 获取 上 下 文 结 构 体 





ngx http mytest ctx tx myctx = ngx http get module ctxl(r,ngx http mytest module); 
// 如 果 之 前 没有 设置 过 上 下 文 ， 那 么 应 当 返 回 








NULL 
if (myctx == NULL) 


/* 必 须 在 当前 请 求 的 内 存 池 


r->pool 中 分 配 上 下 文 结构 体 ， 这 样 请 求 结 束 时 结构 体 占 用 的 内 存 才 会 释放 


bh 
myctx = ngx palloc(r->pool, sizeof (ngx http mytest ctx t+)); 
if (myctx == NULL) 
{ 








return NGX ERROR; 


} 
// 将 刚 分 配 的 结构 体 设置 到 当前 请 求 的 上 下 文中 


ngx http set ctx(r,myctx,ngx http mytest module); 
} 
// 之 后 可 以 任意 使 用 


myctx 这 个 上 下 文 结构 体 








如 果 Nginx 多 次 回调 mytest 模 块 的 相应 方法 ， 那 么 每 次 用 ngx_http_get_module_ctx 宏 取 到 上 
下 文 ，ngx_http_mytest_ctx t 都 可 以 正常 使 用 ，HTTP 框 架 可 以 对 一 个 请 求 保证 ， 无 论调 用 多 少 
次 ngx_http_get_module_ctx 宏 都 只 取 到 同一 个 上 下 文 结构 。 


4.5.3 ” HTTP 框架 如 何 维护 上 下 文 结构 


首先 看 一 下 ngx http request t 结 构 的 ctx 成 员 。 





struct ngx http request s { 


void **ctx; 





可 以 看 到 ，ctx 与 4.3.2 节 中 ngx http conf ctx tt 结构 的 3 个 数组 成 员 非 常 相似 ， 它 们 都 表示 
指向 void* 指 针 的 数组 。HTTP 框 架 就 是 在 ctx 数 组 中 保存 所 有 HTTP 模 块 上 下 文 结 构 体 的 指针 
的 。 


HTTP 框 架 在 开始 处 理 1 个 HTTP 请 求 时 ， 会 在 创建 ngx_http_request t 结 构 后 ， 建 六 ctx 数组 
来 存储 所 有 HTTP 模 块 的 上 下 文 结构 体 指针 (请 求 ngx http request t 的 ctx 成 员 是 一 个 指针 数 
组 ， 其 初始 化 详 见 图 11-2 的 第 9 步 ) 。 





r->ctx = ngx pcalloc(r->pool, sizeof (void*)*ngx http max module); 
if (r->ctx == NULL) { 

ngx destroy pool (r->pool); 

ngx http close connection(c); 

return; 


} 





对 比 4.5.2 市 中 的 两 个 宏 的 定义 可 以 看 出 ，ngx http get module ctx 和 ngx http set ctx 只 是 
去 获取 或 者 设置 ctx 数 组 中 相应 HTTP 模 块 的 指针 而 已 。 
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4.6 小结 


通过 第 3 章 ， 我 们 已 经 了 解 到 开发 一 个 基本 的 HTTP 模 块 可 以 非常 简单 ， 而 本 章 介 绍 的 读 
取 配 置 项 、 使 用 日 志 记 录 必 要 信息 、 为 每 个 HTTP 请 求 定义 上 下 文 则 是 开发 功能 灵活 、 复 
杂 、 高 性 能 的 Nginx 模 块 时 必须 了 解 的 机 制 。 熟 练 掌握 本 章 内 容 ， 是 开发 每 一 个 产品 级 别 
HTTP 模 块 的 先决 条 件 。 
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第 $ 章 ”访问 第 三 方 服 务 











当 需 要 访问 第 三 方 服务 时 ，Nginx 提 供 了 两 种 全 寞 步 方式 来 与 第 三 方 服务 器 通信 : 
upstream 与 subrequest。upstream 可 以 保证 在 与 第 三 方 服 务 器 交互 时 (包括 三 次 握手 建 六 TCP 连 
接 、 发 送 请 求 、 接 收 响应 、 四 次 握手 关闭 TCP 连 接 等 ) 不 会 阻塞 Nginx 进 程 处 理 其 他 请 求 ， 也 
就 是 说 ，Nginx 仍 然 可 以 保持 它 的 高 性 能 。 因 此 ， 在 开发 HTTP 模 块 时 ， 如 采 需 要 访问 第 三 方 
服务 是 不 能 目 己 简单 地 用 套 接 字 编程 实现 的 ， 这 样 会 破坏 Nginx 优 秀 的 全 卉 步 架 构 。 
subrequest 只 是 分 解 复 杂 请 求 的 一 种 设计 模式 ， 它 本 质 上 与 访问 第 三 方 服 务 没有 任何 关系 ， 
但 从 HTTP 模 块 开发 者 的 角度 而 言 ， 使 用 subrequest 访 问 第 三 方 服务 却 很 常用 ， 当 然 ， 
subrequest 访 问 第 三 方 服务 最 终 也 是 基于 upstream 实 现 的 。 这 两 种 机 制 是 HITP 框 架 为 用 户 准 
备 的 、 无 阻 紧 访问 第 三 方 服 务 的 利 占 。 








upstream 和 subrequest 的 设计 目标 是 完全 不 同 的 。 从 名 称 中 可 以 看 出 ，upstream 被 定义 为 
访问 上 游 服 务 器 ， 也 就 是 说 ， 它 把 Nginx 定 义 为 代理 服务 器 ， 首 要 功能 是 透 传 ， 其 次 才 是 以 
TCP 获 取 第 三 方 服务 器 的 内 容 。Nginx 的 HTTP 反 向 代理 模块 就 是 基于 upstream 方 式 实 现 的 。 顾 
名 思 义 ，subrequest 是 从 属 请 求 的 意思 ， 在 这 里 我 们 更 倾向 于 称 它 为 子 请 求 ， 也 就 是 说 ， 
subrequest 将 会 为 客户 请 求 创建 子 请 求 ， 这 是 为 什么 呢 ?” 因 为 异步 无 阻塞 程序 的 开发 过 于 复 
杂 ， 所 以 HTTP 框 架 提 供 了 这 种 机 制 将 一 个 复杂 的 请 求 分 解 为 多 个 子 请 求 ， 每 个 子 请 求 负责 
一 种 功能 ， 而 最 初 的 原始 请 求 负责 构 成 并 发 送 响 应 给 客户 端 。 例 如 ， 用 subrequest 访 问 第 三 
方 服务 ， 一 般 都 是 派生 出 子 请 求 访问 上 游 服务 器 ， 父 请 求 在 完全 取得 上 游 服 务 器 的 响应 后 再 
决定 如 何 处 理 来 自 客户 端的 请 求 。 这 样 做 的 好 处 是 每 个 子 请 求 专注 于 一 种 功能 。 例 如 ， 对 于 
一 个 子 请 求 ， 通 常 在 NGX HTTP_CONTENT PHASE 阶 段 仅 会 使 用 一 个 HTTP 模 块 处 理 ， 这 大 
大 降低 了 模块 开发 的 复杂 度 。 从 HTTP 框 架 的 内 部 来 说 ，subrequest 与 upstream 也 完全 不 同 ， 
upstream 是 从 属于 用 户 请 求 的 ，subrequest 与 原始 的 用 户 请 求 相 比 是 一 个 (或 多 个 ) 独立 的 新 
请 求 ， 只 是 新 的 子 请 求 与 原始 请 求 之 间 可 以 并 发 的 处 理 。 
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因此 ， 当 我 们 希望 把 第 三 方 服务 的 内 容 几 乎 原封 不 动 地 返回 给 用 户 时 ， 一 般 使 用 
upstream 方 式 ， 它 可 以 非常 高 效 地 透 传 HITP《〈 第 12 章 详细 描述 了 upstream 机 制 的 两 种 透 传 方 
式 ) 。 可 如 果 我 们 访问 第 三 方 服 务 只 是 为 了 获取 茶 些 信息 ， 再 依据 这 些 信息 来 构造 啊 应 并 发 
送 给 用 户 ， 这 时 应 该 用 subrequest 访 式 ， 因 为 从 业务 上 来 说 ， 这 是 两 件 事 : 获取 上 游 啊 应 ， 

















再 根据 啊 应 内 容 处 理 请 求 ， 应 由 两 个 请 求 处 理 。 
本 章 仍 然 以 mytest 和 模块 为 例 进 行 说 明 ， 但 会 扩展 mytest 的 功能 。 注 意 ， 文 中 没有 提 及 的 代 


码 (如 定义 mytest 模 块 ) 都 与 第 3 章 完 全 相同 。 
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5.1 upstream 的 使 用 方式 


Nginx 的 核心 功能 一 一 反 向 代理 是 基于 upstream 模 块 〈 该 模块 属于 HTTP 框 架 的 一 部 分 ) 
实现 的 。 在 弄 消 楚 upstream 的 用 法 后 ， 完 全 可 以 根据 自己 的 需求 重 写 Nginx 的 反 疝 代理 功能 。 
例如 ， 反 同 代 理 模 块 是 在 先 接收 完 客 户 请 求 的 HTTP 包 体 后 ， 才 疝 上 游 服 务 占 建立 连接 并 转 
发 请 求 的 。 假 设 用 户 要 上 传 大 小 为 1GB 的 文件 ， 由 于 网 速 限制 ， 文 件 完 整地 到 达 Nginx 需 要 
10 小 时 ， 恰 巧 Nginx 与 上 游 服务 右 间 的 网 络 也 很 差 ( 当 然 这 种 情况 很 少见 ) ， 上 反 回 代理 这 个 
请 求 到 上 游 服务 也 需要 10 小 时 ， 因 此 ， 根 据 用 户 的 网 速 也 许 本 来 只 要 10 个 小 时 的 上 传 过 程 ， 
最 终 可 能 需要 20 个 小 时 才能 完成 。 在 了 解 了 upstream 蕊 能 后 ， 可 以 试看 改变 反 同 代理 模块 的 
这 种 特性 ， 比 如 模仿 squid 反 辐 代 理 模式 ， 在 接收 完整 HTTP 请 求 的 头 部 后 束 与 上 游 服务 器 建 
并 连接 ， 并 开始 将 请 求 辐 上 游 服务 器 透 传 。 

















upstream 的 使 用 方式 并 不 复杂 ， 它 提供 了 8 个 回调 方法 ， 用 户 只 需要 视 目 己 的 需要 实现 其 
中 几 个 回调 方法 整 可 以 了 。 在 了 解 这 8 个 回调 方法 之 前 ， 前 先 要 了 解 upstream 是 如 何 舱 入 到 一 
个 请 求 中 的 。 





从 第 3 章 中 的 内 容 可 以 看 到 ， 模 块 在 处 理 任何 一 个 请 求 时 都 有 ngx_http_request t 结 构 的 对 
象 [， 而 请 求 r 中 又 有 一 个 ngx http_upstream t 类 型 的 成 员 upstream。 


typedef struct ngx http request s ngx http request t; struct ngx http request s { 


ngx http upstream t *upstream; 
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如 果 没 有 使 用 upstream 机 制 ， 那 么 ngx http request t 中 的 upstream 成 员 是 NULL 空 指针 ， 如 
果 使 用 upstream 机 制 ， 那 么 关键 在 于 如 何 设置 r->upstream 成 员 。 





图 $-1 列 出 了 使 用 HTTP 模 块 启 用 upstream 机 制 的 示意 图 。 下 面 以 mytest 模 块 为 例 简单 地 解 
释 一 下 图 5-1。 


1) 首先 需要 创建 上 面 介 绍 的 upstream 成 员 ， 注 意 ，upstream 在 初始 状态 下 是 NULL 空 指 


针 。 可 以 调用 HTTP 框 架 提 供 好 的 ngx_http upstream create 方 法 来 创建 upstream。 


2) 接着 设置 上 游 服 务 器 的 地 址 。 在 HITP 反 向 代理 功能 中 似乎 只 能 使 用 在 nginx.conf 中 配 
置 好 的 上 游 服 务 器 (参见 2.5 节 的 upstream 配 置 块 内 容 ) ， 而 实际 上 upstream 机 制 并 没有 这 种 
要 求 ， 用 户 能 够 以 任意 方式 指定 上 游 服 务 器 的 人 P 地 址 。 例 如 ， 可 以 从 请 求 的 URIL 或 HTTP 头 部 
中 动态 地 获取 上 游 服 务 器 地 址 ，ngx_http_upstream t 中 的 resolved 成 员 就 可 以 帮助 用 户 设置 上 
游 服 务 器 《〈 详 见 5.1.3 节 ) 。 





3) 由 于 upstream 非 常 灵活 ， 在 各 个 执行 阶段 中 都 会 试图 回调 使 用 它 的 HTTP 模 块 实现 的 8 
个 方法 ( 详 见 5.1.4 节 〉 ， 因 此 ， 在 mytest 模 块 例子 中 ， 用 户 要 定义 好 这 些 回 调 方 法 。 


4) 在 mytest 模 块 中 ， 调 用 ngx http_upstream init 方 法 即 可 启动 upstream 机 制 。 注 意 ， 
ngx_ http_mytest_handler 方 法 此 时 必须 返回 NGX DONE， 这 是 在 要 求 HTTP 框 架 不 要 按 阶 段 继 
续 问 下 处 理 请 求 了 ， 同 时 它 告诉 HTTP 框架 请 求 必 须 停留 在 当前 阶段 ， 等 待 某 个 HITP 模 块 主 
动 地 继续 处 理 这 个 请 求 〈 例 如 ， 在 上 游 服 务 器 主动 关闭 连接 时 ，upstream 横 块 束 会 主动 地 继 
续 处 理 这 个 请 求 ， 很 可 能 会 癌 客 户 端 发 送 502 啊 应 码 ) 。 
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阁 用 nsgx_http _upstream _create 方法 为 请 求 创 建 upstream 






设置 第 三 方 服务 带 的 地 址 





设置 upstream 的 回调 方法 





润 用 ngx _http_upstream _init 方法 启动 upstream 


® 


图 5-1 启动 upstream 的 流程 图 


使 用 upstream 模 块 提供 的 ngx_ http upstream init 方 法 后 ，HTTP 框 架 到 底 如 何 运行 upstream 
机 制 呢 ?图 5-2 给 出 了 一 个 常见 的 upstream 执 行 示 意图 ， 它 仪 在 概念 上 表示 主要 流程 ， 与 代码 
的 执行 没有 关系 。 第 12 章 将 详细 介绍 upstream 机 制 到 底 是 如 何 执行 的 。 








图 5-2 所 示 的 upstream 尝 程 包含 了 epoll 模 块 多 次 调度 、 人 处理 一 个 请 求 的 过 程 ， 它 虽然 与 实 
际 代 码 执行 关系 不 大 ， 但 却 指出 了 最 常用 的 3 个 回调 方法 
process_ header、finalize request 是 如 何 回调 的 。 





create request、 
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回调 create _request 方 法 创建 发 往 上 游 的 请 求 


用 无 阻塞 套 接 字 建立 TCP 连 接 并 等 待 建立 成 功 


[ 等 待 上 游 服务 器 的 SYN ACK 包 ] 


[TCF 连接 建立 成 功 ] 
发 送 请 求 到 第 三 方 服 务 
[未 发 送 完全 部 请 求 ] 
[ 发 送 完全 部 请 求 ] 


接收 第 三 方 服务 返回 的 包头 


回调 process _header 方法 处 理 包头 
[未 接收 到 完整 包头 ] 


[ 接收 到 完整 包头 ] 
处 理 第 三 方 服务 返回 的 包 体 
[ 上 游 服 务 器 还 在 发 送 包 体 ] 


<> 


[接收 、 处 理 完 全 部 的 包 体 ] 


回调 finalize _request 并 销毁 请 求 
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图 5-2 upstream 执行 的 一 般 流 程 


人 @@ 注意 wpsteam 提 供 了 3 种 处 理 上 游 服 务 器 包 体 的 方式 ， 包 括 交 由 HTTP 模 决 使 用 
input_flter 回 调 方法 直接 处 理 包 体 、 以 国定 缓冲 区 转发 包 体 、 以 多 个 缓冲 加 磁 瘟 文件 的 方式 
转发 包 体 等 。 在 后 两 种 转发 包 体 的 方式 中 ，upstream 还 与 文件 缓存 功能 紧密 相关 ， 但 为 了 让 
大 家 更 清晰 地 理解 Upstream， 本 章 中 将 不 涉及 文件 缓存 。 


5.1.1 ngx http upstream t 结 构 体 


上 面 了 解 了 upstream 机 制 运行 的 主要 流程 ， 现 在 来 看 一 下 ngx_ http_upstream t 结 构 体 。 
ngx_http_upstream t 结 构 体 里 有 些 成 员 仅仅 是 在 upstream 模 块 内 部 使 用 的 ， 这 里 就 不 一 一 列 出 
了 “由 于 C 语 言 是 面向 过 程 语 言 ， 所 以 ngx http_upstream t 结 构 体 里 会 出 现 第 三 方 HTTP 模 块 
并 不 关心 的 成 员 。 在 12.1.2 节 中 会 完整 地 介绍 ngx http_upstream t 中 的 所 有 成 员 ) 。 





typedef struct ngx http upstream s ngx http upstream 七 struct ngx http upstream s { 


/*request bufs 决 定 发 送 什么 样 的 请 求 给 上 游 服务 器 ， 在 实现 


create request 方 法 时 需要 设置 它 
*/ 


ngx chain t *request bufs; // upstream 访 问 时 的 所 有 限制 性 参数 ， 在 


5.1.2 节 会 论 它 
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ngx http upstream conf 七 *Conf; 


resolved 可 以 直接 指定 上 游 服务 器 地 址 ， 在 


ngx http upstream resolved t *resolved; 


/*buffetr 成 员 存储 接收 自 上 游 服务 器 发 来 的 响应 内 容 ， 由 于 它 会 被 复 用 ， 所 以 具有 下 列 多 种 意义 : 


a) 在 使 用 


process _ header 方 法 解析 上 游 响应 的 包头 时 ， 


buffer 中 将 会 保存 完整 的 响应 包头 ; 


b) 当下 面 的 


buffering 成 员 为 
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1， 而 且 此 时 


upstream 是 向 下 游 转发 上 游 的 包 体 时 ， 


buffer 没 有 意义 ; 


buffering 标 志 位 为 


0 时 ， 


buffer 缓 冲 区 会 被 用 于 反复 地 接收 上 游 的 包 体 ， 进 而 向 下 游 转发 ; 


upstream 并 不 用 于 转发 上 游 包 体 时 ， 


buffer 会 被 用 于 反复 接收 上 游 的 包 体 ， 


HTTP 模 块 实现 的 
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input filter 方 法 需要 关注 它 
#7 
ngx buf t buffer; 


// 构造 发 往 上 游 服务 器 的 请 求 内 容 


ngx int t (*create request) (ngx http request t *r); /* 收 到 上 游 服务 器 的 响应 后 就 会 回调 


process header 方 法 。 如 果 


process header 返 回 


NGX AGAIN， 那 么 是 在 告诉 


upstream 还 没有 收 到 完整 的 响应 包头 ， 此 时 ， 对 于 本 次 


upstream 请 求 来 说 ， 再 次 接收 到 上 游 服 务 器 发 来 的 


TCP 流 时 ， 还 会 调用 
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process header 方 法 处 理 ， 直 到 
process header 芒 数 返回 非 
NGX_AGAIN 值 这 一 阶段 才 会 停止 
类 元 


ngx int t (*process header) (ngx http request t *r); // 销毁 


upstream 请 求 时 调用 


void (*finalize request) (ngx http request t *r, ngx int t rc); // 5 个 可 选 的 回调 方法 


ngx int 七 (*input filter init) (void *data); ngx int t (*input filter) (void *data, ssize t bytes), 


SSL 协 议 访问 上 游 服务 器 


unsigned SSLELS 


/* 在 向 客户 端 转发 上 游 服务 器 的 包 体 时 才 有 用 。 当 


buffering 为 
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1 时 ， 表 示 使 用 多 个 缓冲 区 以 及 磁盘 文件 来 转发 上 游 的 响应 包 体 。 当 


Nginx 与 上 游 间 的 网 速 远大 于 


Nginx 与 下 游客 户 端 间 的 网 加 时， 让 


Nginx 开 辟 更 多 的 内 存 甚 至 使 用 磁盘 文件 来 缓存 上 游 的 响应 包 体 ， 这 是 有 意义 的 ， 它 可 以 减轻 上 游 服 务 器 的 并 发 压力 。 当 


buffering 为 


0 时 ， 表 示 只 使 用 上 面 的 这 一 个 


buffer 缓 冲 区 来 向 下 游 转 发 响应 包 体 


*/ 


unsigned buffering:1; … 





上 文 介绍 过 ，upstream 有 3 种 处 理 上 游 啊 应 包 体 的 方式 ， 但 HTTP 模 块 如 何 告诉 upstream 使 
用 哪 一 种 方式 处 理 上 游 的 啊 应 包 体 呢 ? 妆 请 求 的 ngx_http_request t 结 构 体 中 
subrequest_in_ memory 标志 位 为 1 时 ， 将 采用 第 1 种 方式 ， 即 upstream 不 转发 响应 包 体 到 下 游 ， 
由 HTTP 模块 实现 的 input filter 方 法 处 理 包 体 ， 当 subrequest_in_memory 为 0 时 ，upstream 会 转发 
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响应 包 体 。 当 ngx_http_upstream conf t 配 置 结构 体 中 的 buffering 标 志 位 为 时， 将 开启 更 多 的 
内 存 和 磁盘 文件 用 于 缓存 上 游 的 啊 应 包 体 ， 这 意味 上 游 网 速 更 快 ， 当 buffering 为 0 时 ， 将 使 用 
固定 大 小 的 缓冲 区 〔( 束 是 上 面 介绍 的 buffer 缓 冲 区 〉 来 转发 啊 应 包 体 。 


@ 注意 ”上 述 的 8 个 回调 方法 中 ， 只 有 create_request、process_header、finalize_request 是 





必须 实现 的 ， 其 余 5 个 回调 方法 input_filter_init、 input_filter、 reinit_request、 
abort_request、frewrite_redirect 是 可 选 的 。 第 12 章 会 详细 介绍 如 何 使 用 这 5 个 可 选 的 回调 方法 。 


另外 ， 这 8 个 方法 的 回调 场景 见 5.2 节 。 
5.1.2 ”设置 upstream 的 限制 性 参数 


本 节 介 绍 的 是 ngx http_upstream t 中 的 conf 成 员 ， 它 用 于 设置 upstream 模 块 处 理 请 求 时 的 
参数 ， 包 括 连 接 、 发 送 、 接 收 的 超时 时 间 等 。 





typedef struct { 


// 连接 上 游 服务 器 的 超时 时 间 ， 单 位 为 毫秒 


ngx msec t connect timeout; // 发 送 


TCP 包 到 上 游 服务 器 的 超时 时 间 ， 单 位 为 毫秒 
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TCP 包 到 上 游 服务 器 的 超时 时 间 ， 单 位 为 毫秒 


ngx msec t read timeouty se 


} ngx http upstream conf t; 





ngx_http_upstream conf t 中 的 参数 有 很 多 ，12.1.3 节 会 完整 地 介绍 所 有 成 员 。 事 实 上 ， 
HTTP 反 向 代理 模块 在 nginx.conf 文 件 中 提供 的 配置 项 大 都 是 用 来 设置 ngx_http_upstream_conf t 
结构 体 中 的 成 员 的 。 上 面 列 出 的 3 个 超时 时 间 是 必须 要 设置 的 ， 因 为 它们 默认 为 0， 如 果 不 设 
置 将 永远 无 法 与 上 游 服务 器 建立 起 TCP 连 接 (因为 connect timeout 值 为 0) 。 





使 用 第 4 章 介绍 的 14 个 预 设 方法 可 以 非常 简单 地 通过 nginx.conf 配 置 文件 设置 
ngx_http_upstream_ conf t 结 构 体 。 例 如 ， 可 以 把 ngx_http_upstream conf t 类 型 的 变量 放 到 
ngx http mytest_conf t 结 构 体 中 。 





typedef struct { 


ngx http upstream conf t upstream; 


} ngx http mytest conf t; 
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接 下 来 以 设置 connect timeout 连 接 超 时 时 间 为 例 说 明 如 何 编写 ngx_command t 来 读 取 配置 
文件。 





static ngx Command t ngx http mytest commands[] = {… 





{ ngx string("upstream Connect timeout"), 





NGX_ HTTP LOC CONF|NGX CONF TAKE1， 


ngx conf set msec slot, 








NGX HTTP LOC CONF OFFSET, 





/* 给 出 


connect timeout 成 员 在 


ngx http mytest conf 七 结构 体 中 的 偏 移 字 节 数 





4 


offsetof (ngx http mytest conf t, upstream.connect timeout), NULL }, 








这 样 ，nginx.conf 文 件 中 的 upstream conn timeout 配 置 项 将 被 解析 到 ngx http mytest conf t 
结构 体 的 upstream.connect timeout 成 员 中 。 在 处 理 实际 请 求 时 ， 只 要 把 ngx http mytest conf t 
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ngx_http_ mytest handler 方 法 中 可 以 这 样 设置 : 





ngx http mytest conf t xmycf = (ngx http mytest conf t *) ngx http get module loc confl(r, ngx http mytest mo 














上 面 代码 中 的 r->upstream->conf 是 必须 要 设置 的 ， 否 则 进程 会 月 沉 (crash) 。 


G 注意 ”每 一 个 请 求 都 有 独立 的 ngx_http_upstream_conf t 结 构 体 ， 这 意味 着 每 一 个 请 
求 都 可 以 拥有 不 同 的 网 络 超时 时 间 等 配置 ， 用 户 甚 至 可 以 根据 HITP 请 求 信息 决定 连接 上 游 
服务 器 的 超时 时 间 、 缓 存 上 游 响 应 包 体 的 临时 文件 存放 位 置 等 ， 这 些 都 只 需要 在 设置 f- 
>upstream->conf 时 简单 地 进行 赋值 即 可 ， 有 时 这 非常 有 用 。 





5.1.3 ”设置 需要 访问 的 第 三 方 服 务 器 地 址 


ngx_http_upstream tt 结构 中 的 resolved 成 员 可 以 直接 设置 上 游 服 务 器 的 地 址 。 上 前 先 介绍 一 
下 resolved 的 类 型 。 





typedef struct { 


// 地 址 个 数 


ngx uint t naddrs; 


// 上 游 服 务 器 的 地 址 


sr http: / /Ww | 1 nNuxporobe. con 





socklen t socklen; 


} ngx http upstream resolved t; 





在 ngx_http_upstream resolved tt 结构 的 成 员 中 ， 必 须 设置 的 是 上 面 代码 中 列 出 的 3 个 。 具 
体 设 置 的 例子 可 参见 $.3 节 。 


当然 ， 还 有 其 他 方法 可 以 设置 上 游 服 务 器 地 址 ， 感 兴趣 的 读者 可 以 阅读 upstream 模 块 源 
代码 ， 并 在 nginx.conf 文 件 中 配置 upstream 块 ， 指 定 上 游 服 务 器 的 地 址 。 


5.1.4 设置 回调 方法 


5.1.1 节 介绍 的 ngx_http_upstream tt 结构 体 中 有 8 个 回调 方法 ， 可 根据 需求 及 其 意义 实现 。 
例如 ，3 个 必须 实现 的 回调 方法 可 以 这 么 定义 : 





void mytest upstream finalize request (ngx http request t *r, ngx int t rc); ngx int t mytest upstream create re 





在 5.3 节 中 ， 会 有 一 个 简单 的 例子 说 明 如 何 实现 上 述 3 个 方法 。 


然后 ， 在 ngx_http_mytest_handler 方 法 中 设置 它们 ， 例 如 : 











r->upstream->create request = mytest upstream create request; r->upstream->process header = mytest process stat 








5.1.5 ”如 何 启 动 upstream 机 制 


直接 执行 hgx_http_upstream init 方 法 即 可 启动 upstream 机 制 。 例 如 : 
相关 中 NM http://wWw |1 nNuxporobe. con 





一 = | 


static ngx int t ngx http mytest handler (ngx http request t *r) { 





r->main->count++; 


ngx http upstream init (r); 


return NGX DONE; 








调用 ngx http_upstream init 就 是 在 启动 upstream 机 制 ， 这 时 要 通过 返回 NGX _ DONE 告诉 
HTTP 框 架 暂 停 执行 请 求 的 下 一 个 阶段 。 这 里 还 需要 执行 r->main->countt+， 这 是 在 告诉 HTTP 
框架 将 当前 请 求 的 引用 计数 加 1， 即 告诉 ngx http mytest handler 方 法 暂时 不 要 销毁 请 求 ， 
为 HITP 框 架 只 有 在 引用 计数 为 0 时 才能 真正 地 销毁 请 求 。 这 样 的 话 ，upstream 机 制 接 下 来 才 
能 接管 请 求 的 处 理工 作 。 


@ 注意 ”在 阅读 HTIP 反 向 代理 模块 (ngx_http_proxy_module) 源 代码 时 ， 会 发 现 它 并 
没有 调用 t->main->count+ 二 ， 其 中 proxy 模 块 是 这 样 启动 upstream 机 制 的 : 
nox_http_read_client_request_body(r,nex_http_upstream_init);， 这 表示 读 取 完 用 户 请 求 的 HTTP 包 
体 后 才 会 调用 ngx_http_upstteam_init 方 法 启动 upstteam 机 制 (参见 3.6.4 节 ) 。 由 于 
negx_http_tead_client_request_body 的 第 一 行 有 效 语句 是 t->main->count+ 二 ， 所 以 HTTP 反 向 代理 


模块 不 能 再 次 在 其 代 码 中 执行 +->main->count 十 十 o 


这 个 过 程 看 起 来 似乎 让 人 困惑 。 为 什么 有 时 需要 把 引用 计数 加 1， 有 时 却 不 需要 呢 ? 因 
为 ngx_http_fead_client_tequest_body 读 取 请 求 包 体 是 一 个 异步 操作 (需要 epoll 多 次 调度 才能 完 
成 的 可 称 其 为 异步 操作 ) ，ngx_http_upstream_init 方 法 启用 upstream 机 制 也 是 一 个 异步 操作 ， 
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因此 ， 从 理论 上 来 说 ， 每 执行 一 次 异步 操作 应 该 把 引用 计数 加 1， 而 异步 操作 结束 时 应 该 调 

用 ngx_http_finalize_tfequest 方 法 把 引用 计数 减 1。 另 外 ，ngx_http_tfead_client tequest body 方法 

内 是 加 过 引用 计数 的 ， 而 ngx_http_upstteam_init 方 法 内 却 没有 加 过 引用 计数 (或许 Nginx 将 来 
会 修改 这 个 问题 ) 。 在 HTTP 反 向 代理 模块 中 ， 它 的 ngx_http_proxy_handler 方 法 中 

用 “ngx_http_read_client_request_body(t,ngx_http_upstream_init);” 语 和 句 同时 启动 了 两 个 异步 操 
作 ， 注 意 ， 这 行 语句 中 只 加 了 一 次 引用 计数 。 执 行 这 行 语句 的 ngx_http_proxy_handlet 方 法 返 
回 时 只 调用 ngx_http_finalize_request 方 法 一 次 ， 这 是 正确 的 。 对 于 mytest 模 块 也 一 样 ， 务 必要 
保证 对 引用 计数 的 增加 和 减少 是 配对 进行 的 。 
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5.2 回调 方法 的 执行 场景 


使 用 upstream 方 式 时 最 重要 的 工作 都 会 在 回调 方法 中 实现 ， 为 了 更 好 地 实现 它们 ， 本 市 
将 介绍 调用 这 些 回 调 方 法 的 典型 场景 。 


5.2.1 create request 回 调 方 法 


create_ request 的 回调 场景 最 简单 ， 即 它 只 可 能 被 调用 1 次 “如 有 果 不 司 用 upstream 的 失败 重 
试 机 制 的 话 。 详 见 第 12 章 ) ， 如 图 5-3 所 示 。 下 面 简单 地 介绍 一 下 图 5-3 中 的 每 一 个 步 又 : 


1) 在 Nginx 主 循环 (这 里 的 主 循环 是 指 8.5 节 提 到 的 ngx_worker_process_cycle 方 法 ) 中 ， 
会 定期 地 调用 事件 模块 ， 以 检查 是 否 有 网 络 事 件 发 生 。 





2) 事件 模块 在 接收 到 HTTP 请 求 后 会 调用 HTTP 框 架 来 处 理 。 假 设 接收 、 解 析 完 HTTP 头 
部 后 发 现 应 该 由 mytest 模 块 处 理 ， 这 时 会 调用 mytest 模 块 的 ngx http_mytest handler 来 处 理 。 


3) 这 里 mytest 模 块 此 时 会 完成 5.1.2 节 ~5.1.4 节 中 所 列 出 的 步骤 。 


4) 调用 ngx http_upstream init 方 法 启动 upstream。 
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ry | 到 归 
| 


| 
| | 1 检查 是 否 有 网 络 事件 


pe 

















| | | 
I 1 
2. 经 过 HTTP 核心 模块 调用 mytest 模块 
| | 
| > 5. 设置 回调 丽 数 与 第 三 方 服务 的 地 址 | 
| 


| 
4. 调用 ngx _http _upstream _init 


| 
，。 > 5 检查 文件 缓存 
| 





6. 回调 create _Teduest 


7. 怕 造 完 和 发送 请 求 


| 
，。 > 8 取得 上 游 服务 器 地 址 
| 


| 
9. 使 用 无 阻塞 套 接 字 建 立 TCP 连接 






10. 无 阻塞 调用 返回 


11. ngx_http _upstream _init 返回 


图 5-3 ”create_request 回 调 场 最 的 序列 图 





5) upstream 模 块 会 去 检查 文件 缓存 ， 如 果 缓 存 中 已 经 有 合适 的 啊 应 包 ， 则 会 直接 返回 组 
存 〈 当 然 必 须 是 在 使 用 反问 代理 文件 缓存 的 前 提 下 ) 。 为 了 让 读者 方便 地 理解 upstream 机 
制 ， 本 草 将 不 再 提 及 文件 缓存 。 
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6) 回调 mytest 模 块 已 经 实现 的 create_ request 回调 方法 。 


7) mytest 模 块 通过 设置 r->upstream->request bufs 已 经 决定 好 发 送 什么 样 的 请 求 到 上 游 服 
务 器 。 


8) upstream 模 块 将 会 检查 5.1.3 节 中 介绍 过 的 resolved 成 员 ， 如 果 有 resolved 成 员 的 话 ， 就 
根据 它 设 置 好 上 游 服 务 器 的 地 址 r->upstream->peer 成 员 。 





9) 用 无 阻塞 的 TCP 套 接 字 建立 连接 。 

10) 无 论 连接 是 否 建立 成 功 ， 负 责 建立 连接 的 connecf 方 法 都 会 立刻 返 
11) ngx http_upstream init 返 回 。 

12 ) mytest 模 块 的 ngx http mytest handler 方 法 返回 NGX DONE。 


13) 当 事 件 模块 处 理 完 这 批 网 络 事件 后 ， 将 控制 权 交 还 给 Nginx 主 循环 。 
$.2.2 ”reinit request 回调 方法 

reinit_request 可 能 会 被 多 次 回调 。 它 被 调用 的 原因 只 有 一 个 ， 就 是 在 第 一 次 试图 同上 游 
服务 器 建立 连接 时 ， 如 果 连 接 由 于 各 种 异常 原因 和 失败， 那么 会 根据 upstream 中 conf 参 数 的 策 


略 要 求 再 次 重 连 上 游 服 务 器 ， 而 这 时 融会 调用 reinit request 方 法 了 。 图 5-4 描 述 了 典型 的 


reinit request 调 用 场景 。 
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be Nginx 与 第 三 方 服务 间 Ton; 立成 功 


3. 设 置 request _sent 为 标志 位 1 
1 





4 发 送 请 求 到 第 三 方 服务 





5. 无 阻 赛 发 送 方法 返 





12 .检查 request_sent 时 发 现 已 经 为 1 


13. 回调 reinit_ request 


14. 回调 方法 执行 完毕 
= 


15.TCP 连接 断 开 事件 处 理 完毕 


16. a 处 理 完毕 


5-4 reinit_reqyest 回 调 场 景 的 序列 图 
a 
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下 面 简 单 地 介绍 一 下 图 5$-4 中 列 出 的 步 又。 





1) Nginx 主 循环 中 会 定期 地 调用 事件 模块 ， 检 碍 是 否 有 网 络 事件 发 生 。 


2) 事件 模块 在 确定 与 上 游 服 务 器 的 TCP 连 接 建立 成 功 后 ， 会 回调 upstream 模 块 的 相关 方 
法 处 理 。 


3) upstream 横 块 这 时 会 把 r->upstream->request _ sent 标志 位 置 为 1， 表 示 连 接 已 经 建立 成 功 
了 ， 现 在 开始 向 上 游 服务 器 发 送 请 求 内 容 。 


4) 发 送 请 求 到 上 游 服 务 器 。 





5) 发 送 方法 当然 是 无 阻塞 的 《使 用 了 无 阻 豆 的 套 接 字 ) ， 会 立刻 返回 。 
6) upstream 模 块 处 理 第 2 步 中 的 TCP 连 接 建 立成 功 事 件 。 

7) 事件 模块 处 理 完 本 轮 网 络 事件 后 ， 将 控制 权 交 还 给 Nginx 主 循环 。 

8) Nginx 主 循环 重复 第 1 步 ， 调 用 事件 模块 检查 网 络 事件 。 


9) 这 时 ， 如 果 发 现 与 上 游 服 务 髓 建立 的 TCP 连 接 已 经 异 背 断 开 ， 那 么 事件 模块 会 通知 
upstream 模 块 处 理 它 。 





10) 在 符合 重 试 次 数 的 前 提 下 ，upstream 模 块 会 毫 不 犹 涵 地 再 次 用 无 阻塞 的 套 接 字 试图 
建立 连接 。 


11) 无 论 连接 是 否 建 立成 功 都 立刻 返回 
12〉 这 时 检查 r->upstream->request_sent 标 志 位 ， 会 发 现 它 已 经 被 置 为 1 了 。 


13) 如 果 mytest 模 块 没有 实现 reinit request 方 法 ， 那 么 是 不 会 调用 它 的 。 而 如 果 
reinit request 不 为 NULL 空 指针 ， 就 会 回调 它 。 
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14) mytest 模 块 在 reinit request 中 处 理 完 自己 的 事情 。 
15) 处 理 完 第 9 步 中 的 TCP 连 接 断 开 事件 ， 将 控制 权 交 还 给 事件 模块 。 


16) 事件 模块 处 理 完 本 轮 网 络 事件 后 ， 交 还 控制 权 给 Nginx 主 循环 。 
5.2.3 ”finalize request 回调 方法 


当 调 用 ngx_ http upstream init 启 动 upstream 机 制 后 ， 在 各 种 原因 《无 论 成 功 还 是 失败 ) 导 
致 该 请 求 被 销毁 前 都 会 调用 finalize_ request 方法 〈 人 参见 图 $-1) 。 


在 fnalize _ request 方法 中 可 以 不 做 任何 事情 ， 但 必须 实现 finalize_ request 方法 ， 否 则 Nginx 
会 出 现 空 指针 调用 的 严重 错误 。 


5.2.4 ”process header 回 调 方法 


process_header 是 用 于 解析 上 游 服 务 器 返回 的 基于 TCP 的 响应 头 部 的 ， 因 此 ， 
process_header 可 能 会 被 多 次 调用 ， 它 的 调用 次 数 与 process_header 的 返回 值 有 关 。 如 图 5-5 所 
示 ， 如 果 process_header 返 回 NGX _ AGAIN， 这 意味 着 还 没有 接收 到 完整 的 响应 头 部 ， 如 果 再 
次 接收 到 上 游 服务 器 发 来 的 TCP 流 ， 还 会 把 它 当做 头 部 ， 仍 然 调 用 process_header 处 理 。 而 在 
图 5-6 中 ， 如 果 process_header 返 回 NGX OK (或 者 其 他 非 NGX AGAIN 的 值 ) ， 那 么 在 这 次 
连接 的 后 续 处 理 中 将 不 会 再 次 调用 process_header。 
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Nginx 主 循环 mytest 模块 


网 络 接口 事件 模块 

| | | | 

1. 检 查 是 否 有 网 络 事件 | 
1 

| 2. upstream 读 事件 需要 处 理 

| 
3. 读 取 套 接 字 | 
， 








刻 返回 读 取 到 的 内 容 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
5. 调用 process _header 方 法 解析 包头 





RS process _header 返回 NGX_AGAIN 
1 


| 
| 
8. 再 次 读 取 套 接 字 | 





hd 


11. 本 次 网 络 事件 处 理 完毕 


图 5-5 process_header 回 调 场 最 的 序列 图 


下 面 简单 地 介绍 一 下 图 5-5 中 列 出 的 步 又 。 





1) Nginx 主 循环 中 会 定期 地 调用 事件 模块 ， 检 查 是 否 有 网 络 事件 太 生 。 


2) -再 件 条 乓 素 必 到 十 简 呈 区 痪 年 拓 的 日 心 时 ， Be Oe con 








3) upstream 模 块 这 时 可 以 从 套 接 字 缓 冲 区 中 读 取 到 来 自 上 游 的 TCP 流 。 





4) 读 取 的 响应 会 存放 到 r->upstream->buffer 指 向 的 内 存 中 。 注 意 : 在 未 解析 完 响应 头 部 
前 ， 若 多 次 接收 到 字符 流 ， 所 有 接收 自 上 游 的 响应 都 会 完整 地 存放 到 r->>upstream>buffer 缓 冲 
区 中 。 因 此 ， 在 解析 上 游 响应 包头 时 ， 如 果 buffer 缓 冲 区 全 满 却 还 没有 解析 到 完整 的 响应 头 
部 (也 就 是 说 ，process_header 一 直 在 返回 NGX AGAIN) ， 那 么 请 求 就 会 出 错 。 


5) 调用 mytest 模 块 实现 的 process_header 方 法 。 


6) process_header 方 法 实际 上 就 是 在 解析 r->upstream->buffer 绥 冲 区 ， 试 图 从 中 取 到 完整 
的 响应 头 部 〈 当 然 ， 如 果 上 游 服务 器 与 Nginx 通 过 HTTP 通 信 ， 就 是 接收 到 完整 的 HTTP 头 
部 ) 。 


7) 如 果 process_header 返 回 NGX AGAIN， 那么 表示 还 没有 解析 到 完整 的 啊 应 头 部 ， 下 
次 还 会 调用 process_header 处 理 接收 到 的 上 游 啊 应 。 





8) 调用 无 阻塞 的 读 取 套 接 字 接口 。 


9) 这 时 有 可 能 返回 套 接 字 缓冲 区 已 经 为 空 。 





10) 当 第 2 步 中 的 读 取 上 游 啊 应 事件 处 理 完毕 后 ， 控 制 权 交还 给 事件 模块 。 


11) 事件 模块 处 理 完 本 轮 网 络 事件 后 ， 交 还 控制 权 给 Nginx 主 循环 。 
5.2.5 rewrite redirect 回 调 方法 


在 重 定向 URL 阶 段 ， 如 果实 现 了 rewrite redirect 回 调 方法 ， 那 么 这 时 会 调用 
rewrite redirect。 注 意 ， 本 章 不 涉及 rewrite redirect 方 法， 感 兴 趣 的 读者 可 以 查看 upstream 模 
块 的 ngx_http_upstream rewrite location 方法 。 如 果 upstream 模 块 接收 到 完整 的 上 游 啊 应 头 部 ， 
而 且 由 HTTP 模 块 的 process_header 回 调 方法 将 解析 出 的 对 应 于 Location 的 头 部 设置 到 了 
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ngx http_upstream t 中 的 headers in 成 员 时 ，ngx http upstream process_headers 方 法 将 会 最 终 调 
用 rewrite_redirect 方 法 ( 见 12.5.3 节 图 12-5 的 第 8 步 ) 。 因 此 ，rewrite _ redirect 的 使 用 场景 比较 
少 ， 它 主要 应 用 于 HTTP 有 反问 代 理 模 块 (ngx_http_proxy_module) 。 


5.2.6 input filter init 与 input filter 回调 方法 


input_filter_init 与 input_filter 这 两 个 方法 都 用 于 处 理 上 游 的 啊 应 包 体 ， 因 为 处 理 包 体 前 
HTTP 模 块 可 能 需要 做 一 些 初始 化 工作 。 例 如 ,分配 一 些 内 存 用 于 存放 解析 的 中 间 状 态 等 ， 
这 时 upstream 就 提供 了 input filter_ init 方法。 而 input filter 方 法 就 是 实际 处 理 包 体 的 方法 。 这 两 
个 回调 方法 都 可 以 选择 不 予 实现 ， 这 是 因为 当 这 两 个 方法 不 实现 时 ，upstream 模 块 会 自动 设 
置 它们 为 预 置 方法 〈 上 文 讲 过 ， 由 于 upstream 有 3 种 处 理 包 体 的 方式 ， 所 以 upstream 模 块 准备 
了 3 对 input filter init、input filter 方 法 ) 。 因 此 ， 一 旦 试图 重 定 义 input filter init、input filter 
方法 ， 就 意味 着 我 们 对 upstream 模 块 的 默认 实现 是 不 满意 的 ， 所 以 才 要 重 定义 该 功能 。 此 
时 ， 首 先 必 须要 弄 清 楚 默 认 的 input filter 方 法 到 底 做 了 什么 ， 在 12.6 节 ~12.8 节 介绍 的 3 种 处 理 
包 体 方式 中 ， 都 会 涉及 默认 的 input_filter 方 法 所 做 的 工作 。 











在 多 数 情况 下 ， 会 在 以 下 场景 决定 重新 实现 input_ filter 方法 。 
(1) 在 转 及 上 游 啊 应 到 下 游 的 同时 ， 需 要 做 一 些 特殊 处 理 


例如 ，ngx http memcached module 模 块 会 将 实际 由 memcached 实 现 的 上 游 服务 器 返回 的 
响应 包 体 ， 转 发 到 下 游 的 HTTP 客 户 问 上 。 在 上 述 过 程 中 ， 该 模块 通过 重 定义 了 的 input filter 
方法 来 检测 memcached 协 议 下 包 体 的 结束 ， 而 不 是 完全 、 纯 粹 地 透 传 TCP 流 。 


(2) 当 无 须 在 上 、 下 游 间 转 发 响应 时 ， 并 不 想 等 待 接收 完全 部 的 上 游 响应 后 才 开 始 处 
理 请 求 





在 不 转发 响应 时 ， 通 常会 将 响应 包 体 存 放 在 内 存 中 解析 ， 如 果 试 图 接收 到 完整 的 响应 后 
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再 来 解析 ， 由 于 啊 应 可 能 会 非常 大 ， 这 会 占用 大 量 内 存 。 而 重 定义 了 input_filter 方 法 后 ， 可 
以 每 解析 完 一 部 分 包 体 ， 就 释放 一 些 内 存 。 


重 定 义 input filter 方 法 必须 符合 一 些 规则 ， 如 怎样 取 到 刚 接收 到 的 包 体 以 及 如 何 释放 组 
冲 区 使 得 固定 大 小 的 内 存 绥 冲 区 可 以 重复 使 用 等 。 注 意 ， 本 章 的 例子 并 不 涉及 input filter 方 
法 ， 读 者 可 以 在 第 12 章 中 找到 input filter 方 法 的 使 用 方式 。 
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$.3 ”使 用 upstream 的 示例 


下 面 以 一 个 简单 且 能 够 运行 的 示例 帮助 读者 理解 如 何 使 用 upstream 机 制 。 这 个 示例 要 实 
现 的 功能 很 简单 ， 即 以 访问 mytest 模 块 的 URIL 参 数 作 为 搜索 引擎 的 关键 字 ， 用 upstream 方 式 访 
问 google， 查 询 URL 里 的 参数 ， 然 后 把 google 的 结果 返回 给 用 户 。 这 个 场景 非常 适合 使 用 
upstream 方 式 ， 因 为 Nginx 访 问 google 的 服务 器 使 用 的 是 HTTP， 它 当然 符合 upstream 的 使 用 场 
景 : 上 游 服 务 器 提供 基于 TCP 的 协议 。 上 文 讲 过 ，upstream 提 供 了 3 种 处 理 包 体 的 方式 ， 这 里 
选择 以 固定 缓冲 区 向 下 游客 户 端 转发 go0gle 返 回 的 包 体 (HTTP 的 包 体 〉 的 方式 。 


例如 ， 如 果 访 问 的 URL 是 /test?lumia， 那 么 在 nginx.conf 中 可 以 这 样 配置 location。 


location /test { 


mytest; 


mytest 模 块 将 会 使 用 upstream 机 制 癌 www.google.com 发 送 搜索 请 求 ， 它 的 请 求 URL 
是 /search?q=lumia，google 返 回 的 包头 将 在 mytest 模 块 中 解析 并 决定 如 何 转发 给 用 户 ， 而 包 体 
将 会 被 透 传 给 用 户 。 


这 里 继续 以 mytest 模 块 为 例 来 说 明 如 何 使 用 upstream 达 成 上 述 效 果 。 
5.3.1 upstream 的 各 种 配置 参数 


每 一 个 HTTP 请 求 都 会 有 独立 的 ngx_http upstream conf t 结 构 体 ， 出 于 简单 考虑 ， 在 
mytest 模 块 的 例子 中 ， 所 有 的 请 求 都 将 共享 同一 个 ngx_http_upstream conf t 结 构 体 ， 因 此 ， 这 


里 把 它 放 到 ngx http mytest_conf t 配 置 结构 体 中 ， 如 下 所 示 。 . 
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二 一 


typedef struct { 


ngx http upstream conf t upstream; 


} ngx http mytest conf 七 








在 启动 upstream 前 ， 先 将 ngx_http mytest_conf t 下 的 upstream 成 员 赋 给 r->upstream->conf 成 
员 ， 可 参考 $.3.6 节 中 的 示例 代码 。 


ngx_http upstream_conf t 结 构 中 的 各 成 员 可 以 通过 第 4 章 中 介绍 的 方法 ， 即 用 预 设 的 配置 
项 解析 参数 来 赋值 ， 如 5.1.2 节 中 的 例子 所 示 。 出 于 方便 ， 这 里 直接 人 硬 编 码 到 create_loc_conf 
回调 方法 中 了 ， 如 下 所 示 。 





static void* ngx http mytest create loc conf(ngx conf t *cf) { 





ngx http mytest conf 七 *mycf; 





mycf = (ngx http mytest conf t *)ngx pcalloc(cf->pool, sizeof(ngx http mytest conf t)); if (mycf == NULL) 








return NULL; 


/* 以 下 简单 的 硬 编码 


ngx http upstream conf 结构 中 的 各 成 员 ， 如 超时 时 间 ， 都 设 为 


HTTP 反 向 代理 模块 的 默认 值 
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*/ 








mycf->upstream.connect timeout = 60000; mycf->upstream.send timeout = 60000; mycf->upstream.read timeout = { 


buffering 已 经 决定 了 将 以 国定 大 小 的 内 存 作 为 缓冲 区 来 转发 上 游 的 响应 包 体 ， 这 块 国定 缓冲 区 的 大 小 就 是 


buffer size。 如果 


buffering 为 


1， 就 会 使 用 更 多 的 内 存 缓存 来 不 及 发 往 下 游 的 响应 。 例 如 ， 最 多 使 用 


bufs .num 个 缓冲 区 且 每 个 缓冲 区 大 小 为 


bufs.size。 另 外 ， 还 会 使 用 临时 文件 ， 临 时 文件 的 最 大 长 度 为 


max temp file size*/ 
mycf->upstream.buffering = 0; 
mycf->upstream.bufs.num = 8; 


mycf->upstream.bufs.size = ngx pagesize; mycf->upstream.buffer size = ngx pagesize; mycf->upstream.busy buf: 
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upstream 在 解析 完 上 游 服务 器 返回 的 包头 时 ， 会 调用 


ngx http upstream process headers 方 法 按照 


hide headers 成 员 将 本 应 转发 给 下 游 的 一 些 


HTTP 头 部 隐藏 )， 这 里 将 它 赋 为 


NGX CONF UNSET PTR ， 这 是 为 了 在 





merge 合 并 配置 项 方法 中 使 用 


upstream 模 块 提供 的 





ngx http upstream hide headers hash 方 法 初始 化 


hide headers 成 员 


*/ 











mycf->upstream.hide headers = NGX CONF UNSET PTR; mycf->upstream.pass headers = NGX CONF UNSET PTR; returnt 
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hide_headers 的 类 型 是 ngx array {t 动 态 数组 〈 实 际 上 ，upstream 模 块 将 会 通过 hide_ headers 
来 构造 hide headers hash 散 列表 ) 。 由 于 upstream 模 块 要 求 hide headers 不 可 以 为 NULL， 所 以 
必须 要 初始 化 hide_headers 成 员 。upstream 模 块 提供 了 ngx http upstream hide headers hash 方 法 
来 初始 化 hide headers， 但 仅 可 用 在 合并 配置 项 方法 内 。 例 如 ， 在 下 面 的 
ngx http_mytest merge loc conf 方 法 中 就 可 以 使 用 ， 如 下 所 示 ， 





static char *ngx http mytest merge loc conf (ngx conf 七 cf void parent, void *child) { 





ngx http mytest conf 七 *prev = (ngx http mytest conf t *)parent; ngx http mytest conf 七 *conf = (ngx http m: 











hash.max size = 100; 


hash.bucket size = 1024; 


hash.name = "proxy headers hash"; 





if (ngx http upstream hide headers hash(cf, &conf->upstream, &prev->upstream, ngx http Proxy hide headers, 





return NGX CONF ERROR; 





return NGX CONF OR; 





$532 ”请求 了 上下文 


本 节 介 绍 的 例子 就 必须 要 使 用 上 下 文才 能 正确 地 解析 upstream 上 游 服务 器 的 响应 包 ， 
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为 upstream 模 块 每 次 接收 到 一 段 TCP 流 时 都 会 回调 mytest 模 块 实现 的 process_header 方 法 解析 ， 
这 样 就 需要 有 一 个 上 下 文保 存 解析 状态 。 在 解析 HITP 啊 应 行 时 ， 可 以 使 用 HTTP 框架 提供 的 
ngx_http_status_t 结 构 ， 如 下 所 示 。 








typedef struct { 


ngx uint t code; 
ngx uint t count; 
UU Char *start; 
u char *end; 


} ngx http status t; 





把 ngx_http_status_t 结 构 放 到 上 下 文中 ， 并 在 process_header 解 析 响 应 行 时 使 用 ， 如 下 所 


小 。 





typedef struct { 


ngx http status t status; 


} ngx http mytest ctx 七 








在 5.3.4 市 实现 process_header 的 代码 中 ， 可 以 学 会 如 何 使 用 ngx_http_status_t 结 构 。 


5.3.3 ”在 create request 方 法 中 构造 请 求 


这 里 定义 的 mytest_upstream create request 方 法 用 于 创建 发 送 给 上 游 服 务 器 的 HTTP 请 
求 ，upstream 模 块 将 会 回调 它 ， 实 现 如 下 。 








static ngx int t mytest upstream Create request (ngx http request 七 *r) { 





/* 发 往 


google 上 游 服务 器 的 请 求 很 简单 ， 就 是 模仿 正常 的 搜索 请 求 ， 以 


/searchq=… 的 


URL 来 发 起 搜索 请 求 。 


backendQueryLine 中 的 


SV 等 转化 格式 的 用 法 ， 可 参见 表 


4-7*/ 





static ngx str t backendQueryLin 








ngx string ("GET searchgq=%®V HTTPl1.1\r\nHost: www.google.com\r\nConnection: close\r\n\r\n"); ng: 


epoll 多 次 调度 


send 才 能 发 送 完 成 ， 这 时 必须 保证 这 段 内 存 不 会 被 释放 ; 另 一 个 好 处 是 ， 在 请 求 结束 时 ， 这 上 段 内 存 会 被 自动 释放 ， 降 低 内 存 泄漏 的 可 能 


二 / 
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ngx buf tx b = ngx create temp buf(r->pool, queryLineLen); if (b == NULL) 


return NGX ERROR; 





// last 要 指向 请 求 的 末尾 


b->last = b->pos + queryLineLen; 


// 作用 相当 于 


snprintf， 只 是 它 支持 表 


4-7 中 列 出 的 所 有 转换 格式 


ngx snprintf (b->pos, queryLineLen ， 


(char*)backendQueryLine.data, &r->args); /* r->upstream->request bufs 是 一 个 


ngx_chain tt 结构 ， 它 包含 着 要 发 送 给 上 游 服务 器 的 请 求 
*/ 
r->upstream->request bufs = ngx alloc chain link(r->pool); if (r->upstream->request bufs == NULL) return NGX 


// ”request bufs 在 这 里 只 包含 


EB 
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ngx_ buf 七 缓冲 区 





r->upstream->request bufs->buf = b; r->upstream->request bufs->next = NULL; r->upstream->request sent = 0; 





r->upstream->header sent = 0; 


// ”header hash 不 可 以 为 


r->header hash = 1; 


return NGX OK; 





5.3.4 ”在 process_header 方 法 中 解析 包头 


process_header 负 责 解 析 上 游 服 务 器 发 来 的 基于 TCP 的 包头 ， 在 本 例 中 ， 就 是 解析 HTTP 
响应 行 和 HTTP 头 部 ， 因 此 ， 这 里 使 用 mytest process_status_line 方 法 解析 HTTP 响 应 行 ， 使 用 
mytest_ upstream process_header 方 法 解析 http 响 应 头 部 。 之 所 以 使 用 两 个 方法 解析 包头 ， 这 也 
是 HITP 的 复杂 性 造成 的 ， 因 为 无 论 是 响应 行 还 是 响应 头 部 都 是 不 定 长 的 ， 都 需要 使 用 状态 
机 来 解析 。 实 际 上 ， 这 两 个 方法 也 是 通用 的 ， 它 们 适用 于 解析 所 有 的 HITP 响 应 包 ， 而 且 这 
两 个 方法 的 代码 与 ngx_http proxy module 模 块 的 实现 几乎 是 完全 一 致 的 。 











static ngx int. t 


mytest process status line(ngx http request t *r) { 
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size 七 len; 


ngx int 七 rc; 


ngx http upstream t *u; 


// 上 下 文中 才 会 保存 多 次 解析 


HTTP 响 应 行 的 状态 ， 下 面 首先 取出 请 求 的 上 下 文 


ngx http mytest ctx tx ctx = ngx http get module ctx(r,ngx http mytest module); if (ctx == NULL) { 











return NGX ERROR; 


u= r->upstream; 


/*HTTP 框 架 提供 的 


ngx http parse status 1Line 方 法 可 以 解析 





HTTP 响 应 行 ， 它 的 输入 就 是 收 到 的 字符 流 和 上 下 文中 的 


ngx http status 七 结构 
A 


rc = ngx http parse status line(r, &u->buffer, &ctx->status); // 返回 


TiNNNinNnnn http://wWwWw linuxorobe.con 








NGX_ AGAIN 时 ， 表 示 还 没有 解析 出 完整 的 


HTTP 响 应 行 ， 需 要 接收 更 多 的 字符 流 再 进行 解析 


4 


if (rc == NGX AGAIN) { 


return rc; 


NGX_ERROR 时 ， 表 示 没 有 接收 到 合法 的 





HTTP 响 应 行 


if (rc == NGX ERROR) { 








ngx_1l0og error (NGX LOG ERR, r->connection->log, 0, "upstream sent no Valid HTTP/1.0 header"); r->http ve 


/* 以 下 表示 在 解析 到 完整 的 


HTTP 响 应 行 时 ， 会 做 一 些 简 单 的 赋值 操作 ， 将 解析 出 的 信息 设置 到 
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r->upstream->headers in 结 构 体 中 。 当 


upstream 解 析 完 所 有 的 包头 时 ， 会 把 


headers_ in 中 的 成 员 设 置 到 将 要 向 下 游 发 送 的 


r->headers _ out 结构 体 中 ， 也 就 是 说 ， 现 在 用 户 向 


headers_in 中 设置 的 信息 ， 最 终 都 会 发 往 下 游客 户 端 。 为 什么 不 直接 设置 





r->headers out 而 要 多 此 一 举 呢 ? 因为 


upstream 和 希望 能 够 按照 


ngx_http_upstream conf 七 配置 结构 体 中 的 


hide heaqers 等 成 员 对 发 往 下 游 的 响应 头 部 做 统一 处 理 
if (u->state) { 
u->state->status = ctx->status.code; } 


u->headers in.status n = ctx->status.code; len = ctx->status.end - ctx->status.start; u->headers in.status . 
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return NGX ERROR; 





ngx memcpy (u->headers in.status line.data, ctx->status.start, len); /* 下 一 步 将 开始 解析 


HTTP 头 部 。 设 置 


process_header 回 调 方法 为 


mytest upstream process header， 之 后 再 收 到 的 新 字符 流 将 由 


mytest upstream process header 解 析 


机 





Uu->process header = mytest upstream process header; /* 如 果 本 次 收 到 的 字符 流 除了 


HTTP 响 应 行 外 ， 还 有 多 余 的 字符 ， 那 么 将 由 


mytest upstream process header 方 法 解析 


*/ 


return mytest upstream process header (r); } 





mytest_upstream process_header 方 法 可 以 解析 HTTP 啊 应 头 部 ， 而 这 个 例子 只 是 简单 地 把 
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上 游 服务 器 发 送 的 HITP 头 部 添加 到 了 请 求 r->upstream->headers_ in.headers 链 表 中 。 如 果 有 需 
要 特殊 处 理 的 HITP 头 部 ， 那 么 也 应 该 在 mytest upstream process_header 方 法 中 进行 。 





static ngx int t mytest upstream process header (ngx http request 七 *r) { 


ngx int 七 re 
ngx table elt t *h; 
ngx http upstream header t *hh; 


ngx http upstream main conf 七 *umcf; 


upstream 模 块 配置 项 


ngx http upstream main conf 七 取出 来 ， 目 的 只 有 一 个 ， 就 是 对 将 要 转发 给 下 游客 户 端的 


HTTP 响 应 头 部 进行 统一 处 理 。 该 结构 体 中 存储 了 需要 进行 统一 处 理 的 


HTTP 头 部 名 称 和 回调 方法 


4 


umcf = ngx http get module main conf(r, ngx http upstream module); // 循环 地 解析 所 有 的 





HTTP 头 部 
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/* HTTP 框 架 提 供 了 基础 性 的 


ngx http parse header line 方 法 ， 它 用 于 解析 





HTTP 头 部 


*/ 


rc = ngx http parse header linel(r, &r->upstream->buffer, 1); // 返回 





NGX_OK 时 ， 表 示 解 析出 一 行 


HTTP 头 部 


if (rc == NGX OK) { 


// 向 


headers in.headers 这 个 


ngx list tt 链表 中 添加 
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HTTP 头 部 


h = ngx list Push(&r->upstream->heaqers in.headers); if (h == NULL) { 





return NGX ERROR; 


// 下 面 开 始 构造 刚刚 添加 到 


headers 链 表 中 的 


HTTP 头 部 





h->hash = r->header hash; h->key.len = r->header name end - r->header name Start” h->value.len = r- 


HTTP 头 部 的 内 存 空间 


h->key.data = ngx pnalloc(r->pool, h->key.len + 1 + h->value.len + 1 + h->key.len); if (h->key.data 


return NGX ERROR; 








h->value.data = h->key.data + h->key.len + 1; h->lowcase key = h->key.data + h->key.len + 1 + h->va 
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ngx memcpy (h->lowcase key, r->lowcase header, h->key.len); } else { 


ngx strlow(h->lowcase key, h->key.data, h->key.len); } 


// upstream 模 块 会 对 一 些 


HTTP 头 部 做 特殊 处 理 


hh = ngx hash find(&umcf->headers in hash, h->hash, h->lowcase key, h->key.len); if (hh && hh->hand 


return NGX ERROR; 





continue; 


/* 返 回 





NGX HTTP PARSE HEADER DONE 时 ， 表 示 响 应 中 所 有 的 




















HTTP 头 部 都 解析 完毕 ， 接 下 来 再 接收 到 的 都 将 是 


HTTP 包 体 


y 





if (rc == NGX HTTP PARSE HEADER DONE) { 
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HTTP 头 部 时 没有 发 现 


server 和 


date 头 部 ， 那 么 下 面 会 根据 


HTTP 协 议 规范 添加 这 两 个 头 部 


*/ 
if (r->upstream->headers in.server == NULL) { 
h = ngx list push(&r->upstream->headers in.headers); if (h == NULL) { 





return NGX ERROR; 


h->hash = ngx hash(ngx hash (ngx hash (ngx hash( 


ngx hash('s', ‘'e'), 'r'), 'Vv'), 'e'), 'r'); ngx str set(&h->key, "Server"); 
if (r->upstream->headers in.date == NULL) { 
h = ngx list push(&r->upstream->headers in.headers); if (h == NULL) { 


return NGX ERROR; 





h->hash = ngx hash(ngx hash(ngx hash('d', 'a'), 't'), 'e'); ngx str set(&h->key, "Date"); ngx si 
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return NGX OR; 


/* 如 果 返 回 


NGX_AGAIN， 则 表示 状态 机 还 没有 解析 到 完整 的 


HTTP 头 部 ， 此 时 要 求 


upstream 模 块 继续 接收 新 的 字符 流 ， 然 后 交 由 


process_header 回 调 方法 解析 


4 
if (rc == NGX AGAIN) { 
return NGX AGAIN; 
} 
// 其 他 返回 值 都 是 非法 的 
ngx log error (NGX_ LOG ERR, r->connection->log, 0, "upstream Sent invalid header"); return NGX HTTP UPSTI 








pt 部 种 宫 Ee SIN tu 7 WT LE 人 个 《如 





果 有 的 话 ) 直接 转发 到 下 游客 户 端 。 
5.3.5 在 finalize request 方 法 中 释放 资源 


当 请 求 结束 时 ， 将 会 回调 finalize_request 方 法 ， 如 果 我 们 希望 此 时 释放 资源 ， 如 打开 的 
句柄 等 ， 那 么 可 以 把 这 样 的 代码 添加 到 finalize_request 方 法 中 。 本 例 中 定义 了 
mytest_upstream finalize_request 方 法 ， 由 于 我 们 没有 任何 需要 释放 的 资源 ， 所 以 该 方法 没有 
完成 任何 实际 工作 ， 只 是 因为 upstream 模 块 要 求 必 须 实现 finalize_request 回 调 方 法 ， 如 下 所 


作 \。 








static void 


mytest upstream finalize request (ngx http request t *r, ngx int t rc) { 





ngx log error (NGX LOG DEBUG, r->connection->log,0, "mytest upstream finalize request"); } 





5.3.6 ”在 ngx http mytest handler 方 法 中 启动 upstream 


在 开始 介入 处 理 客 户 端 请 求 的 ngx_http_mytest_ handler 方 法 中 启动 upstream 机 制 ， 而 何 时 
请 求 会 结束 ， 则 视 Nginx 与 上 游 的 google 服 务 器 间 的 通信 而 定 。 通 利 ， 在 局 动 upstream 时 ， 我 
们 将 决定 以 何 种 方式 处 理 上 游 啊 应 的 包 体 ， 前 文 资 过， 我 们 会 原封 不 动 地 转发 google 的 啊 应 
包 体 到 客户 端 ， 这 一 行为 是 由 ngx_http_request t 结 构 体 中 的 subrequest_in_ memory 标志 位 诀 定 
的 ， 默 认 情 况 下 ，subrequest_in_memory 为 0， 即 表示 将 转发 上 游 的 包 体 到 下 游 。 在 5.3.1 节 中 
介绍 过 ， 当 ngx_http_upstream_conf t 结 构 体 中 的 buffering 标 志 位 为 0 时 ， 意 味 着 以 固定 大 小 的 
绥 冲 区 来 转发 包 体 。 











static ngx int t ngx http mytest handler (ngx http request t *r) { 
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HTTP 上 下 文 结 构 体 


ngx http mytest ctx t 





ngx http mytest ctx tx myctx = ngx http get module ctx (rngx http mytest module); if (myctx == NULL) 








myctx = ngx palloc(r->pool, sizeof (ngx http mytest ctx t)); if (myctx == NULL) 





return NGX ERROR; 





// 将 新 建 的 上 下 文 与 请 求 关联 起 来 


ngx http set ctx(r,myctx,ngx http mytest module); } 


/* 对 每 


1 个 委 使 用 


upstream 的 请 求 ， 必 须 调用 且 只 能 调用 


1 次 
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ngx http upstream _ create 方法 ， 它 会 初始 化 


r->upstream 成 员 














*/ 
if (ngx http upstream create(r) != NGX OK) { 
ngx 1og error (NGX LOG ERR, r->connection->log, 0,"ngx http upstream create() failed"); return NGX ERROR; 
} 
// 得 到 配置 结构 体 
ngx http mytest conf 七 
ngx http mytest conf 七 *mycf = (ngx http mytest conf 七 *) ngx http get module loc confl(r, ngx http mytest 











r->upstream->conf 成 员 


u->conf = &mycf->upstream; 


// 决定 转发 包 体 时 使 用 的 缓冲 区 


u->buffering = mycf->upstream.buffering; // 以 下 代码 开始 初始 化 


resolved 结 构 体 ， 用 来 保存 上 游 服务 器 的 地 址 
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uU->resolved = (ngx http upstream resolved t*) ngx pcalloc(r->pool, sizeof (ngx http upstream resolved 七 ) ) ; i: 





ngx 1og error (NGX LOG ERR, r->connection->log, 0, "ngx pcalloc resolved error. %s.", strerror(errno)); rt 


// 这 里 的 上 游 服务 器 就 是 


www.google .com 


static struct sockaddr in backendSockAddr; struct hostent pHost = gethostbyname((char) "www.google.com"); i: 





ngx log error (NGX LOG ERR, r->connection->log, 0, "gethostbyname fail. %s", strerror(errno)); return NGX 


// 访问 上 游 服 务 器 的 


80 端 口 


backendSockAddr.sin family = AP INET; 





backendSockAddr.sin port = htons((in port t) 80); char* pDmsIP = inet ntoa(*(struct in addr*) (pHost->h add 


resolved 成 员 中 


于 平川 中 村 > 后 再 下 FI 后 中 中 Fofrxhad] *) sacEEt /WAAL XrOBe:: Cope 





// 设置 


3 个 必须 实现 的 回调 方法 ， 也 就 是 


5.3.3 节 ~ 


3 个 方法 








Uu->create request = mytest upstream create request; u->process header = mytest process status line; u->fina. 





count 成 员 加 


r->main->count++; 


// 启动 
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upstream 


ngx http upstream init(r); 


// 必须 返回 


NGX DONE 








return NGX DONE; 


到 此 为 止 ， 高 性 能 地 访问 第 三 方 服务 的 upstream 例 子 就 介绍 完了 。 在 本 例 中 ， 可 以 完全 
异步 地 访问 第 三 方 服务 ， 并 发 访问 数 也 只 会 受制 于 物理 内 存 的 大 小 ， 完 全 可 以 轻松 达到 几 十 
万 的 并 发 TCP 连 接 。 
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5.4 ”subrequest 的 使 用 方式 


subrequest 是 由 HTTP 框 架 提供 的 一 种 分 解 复杂 请 求 的 设计 模式 ， 它 可 以 把 原始 请 求 分 解 
为 许多 子 请 求 ， 使 得 诸多 请 求 协 同 完 成 一 个 用 户 请 求 ， 并 且 每 个 请 求 只 关注 于 一 个 功能 。 它 
与 访问 第 三 方 服务 及 upstream 机 制 有 什么 关系 呢 ? 首先 ， 只 要 不 是 完全 将 上 游 服务 堪 的 啊 应 
包 体 转发 到 下 游客 户 端 ， 基 本 上 都 会 使 用 subrequest 创 建 出 子 请 求 ， 并 由 子 请 求 使 用 upstream 
机 制 访问 上 游 服 务 嚣 ， 然 后 由 父 请 求 根 据 上 游 啊 应 重新 构造 返回 给 下 游客 户 端 的 啊 应 。 其 
次 ， 在 HTTP 框 架 的 设计 上 ，subrequest 与 upstream 也 是 密切 相关 的 。 例 如 ， 上 文 讲 过 ， 描 述 
HTTP 请 求 的 ngx_http_request t 结 构 体 中 有 一 个 标志 位 subrequest_in_ memory， 它 决定 upstream 
对 待 上 游 啊 应 包 体 的 行为 。 但 是 从 名 字 上 我 们 可 以 看 到 ， 它 是 与 subrequest 有 关 的 ， 实 际 
上 ， 在 创建 子 请 求 的 方法 中 就 可 以 设置 subrequest_ in_ memory。 








subrequest 设 计 的 基础 是 生成 一 个 〈 子 ) 请 求 的 代价 要 非常 小 ， 消 耗 的 内 存 也 要 很 少 ， 
并 且 不 会 一 直 占 用 进程 资源 。 因 此 ， 每 个 请 求 都 应 该 做 简单 、 独 立 的 工作 ， 而 由 多 个 子 请 求 
合成 为 一 个 父 请 求 向 客户 端 提供 完整 的 服务 。 在 Nginx 中 ， 大 量 功能 复杂 的 模块 都 是 基于 


subrequest 实 现 的 。 
使 用 subrequest 的 方式 要 比 upstream 简 单 得 多 ， 只 需要 完成 以 下 4 步 操 作 即 可 。 
1) 在 nginx.conf 文 件 中 配置 好 子 请 求 的 处 理 方式 。 
2) 启动 subrequest 子 请 求 。 
3) 实现 子 请 求 执行 结束 时 的 回调 方法 。 
4) 实现 父 请 求 被 激活 时 的 回调 方法 。 


下 面 依次 说 明 这 4 个 步 又 。 
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5.4.1 配置 子 请 求 的 处 理 方 式 


实际 上 ， 子 请 求 的 处 理 过 程 与 普通 请 求 完 全 相同 ， 也 需要 在 nginx.conf 中 配置 相应 的 模块 
来 处 理 。 子 请 求 与 普通 请 求 的 不 同 之 处 在 于 ， 子 请 求 是 由 父 请 求生 成 的 ， 不 是 接收 客户 端 友 
来 的 网 络 包 再 由 HTTP 框 架 解 析出 的 。 配置 处 理子 请 求 的 模块 与 普通 请 求 完 全 相同 ， 可 以 任 
意 地 使 用 HTTP 官 方 模块 、 第 三 方 模块 来 处 理 。 本 章 中 将 以 访问 第 三 方 服务 为 例 ， 因 此 会 使 
用 ngx_http_proxy_module 有 反问 代理 模块 来 处 理子 请 求 ( 注 意 ， 这 里 并 没有 使 用 反 癌 代理 的 转 
发 啊 应 功能 ， 而 只 是 把 啊 应 接收 到 Nginx 的 内 存 中 ) ， 但 在 实际 应 用 中 不 限于 此 。 














假设 我 们 生成 的 子 请 求 是 以 URI 为 /list 开 头 的 请 求 ， 使 用 ngx http proxy module 模 块 让 子 
请 求 访问 新 浪 的 hq.sinajs.cn 股 票 服务 器 ， 那 么 可 以 在 nginx.conf 中 这 样 设置 : 





location /list { 
proxy pass http:// hq.sinajs.cn 


/* 不 希望 第 三 方 服务 发 来 的 


HTTP 包 体 做 过 


gzip 压 缩 ， 因 为 我 们 不 想 在 子 请 求 结 束 时 要 对 响应 做 


gzip 解 压缩 操作 


wy 








proxy set header Accept-Encoding "" 


这 样 ， 在 5.4.4 节 中 ， 如 果 生 成 的 子 请 求 是 以 /list 开 头 的 ， 就 会 使 用 反 向 代理 模块 去 访问 
新 浪 服 务 器 ， 并 在 接收 完 新 浪 服 务 器 的 啊 应 包 后 调用 5.4.2 市 中 介绍 的 回调 方法 。 


5.4.2 ”实现 子 请 求 处 理 完毕 时 的 回调 方法 





Nginx 在 子 请 求 正 常 或 者 异常 结束 时 ， 都 会 调用 ngx http post subrequest pt 回调 方法 ， 如 


下 所 示 。 
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typedef ngx int 七 (xngx http post subrequest pt) (ngx http request t r,void data, ngx int t rc); 





如 何 把 这 个 回调 方法 传递 给 subrequest 子 请 求 呢 ? 要 建立 ngx http post subrequest t 结 构 
体 : 





typedef struct { 
ngx http post subrequest pt handler; 
void *data; 

} ngx http post subrequest 七; 





在 生成 ngx_http post subrequest t 结 构 体 时 ， 可 以 把 任意 数据 赋 给 这 里 的 data 指 针 ， 
ngx_http_post_subrequest_pt 回 调 方 法 执行 时 的 data 参 数 就 是 ngx_http_post_subrequest t 结 构 体 中 
的 data 成 员 指 针 。 


ngx_http_post_subrequest_pt 回 调 方法 中 的 rc 参数 是 子 请 求 在 结束 时 的 状态 ， 它 的 取 值 则 
是 执行 ngx_http_finalize_ request 销毁 请 求 时 传递 的 rc 参数 〈 对 于 本 例 来 说 ， 由 于 子 请 求 使 用 反 
向 代理 模块 访问 上 游 HTTP 服 务 器 ， 所 以 rc 此 时 是 HITP 响 应 码 。 例 如 ， 在 正常 情况 下 ，fFrc 会 
是 200) 。 相 应 源 代码 如 下 : 





void 
ngx http finalize request (ngx http request t *r, ngx int t rc) 
{ 


// 如 果 当 前 请 求 属于 某 个 原始 请 求 的 子 请 求 


if (r != r->main && r->post subrequest) { 
rc = r->post subrequest->handler(r, r->post subrequest->data, rc); 


} 





上 面 代码 中 的 r 变 量 是 子 请 求 〈 不 是 父 请 求 ) 。 


和 PP 同和 加 这 法 屏 醚 请 下 六 活 局 的 we 有 





法 很 简单 ， 首 先 要 找 出 父 请 求 ， 例 如 : 





ngx http request t *pr = r->parent; 





然后 将 实现 好 的 ngx_http_event_handler_pt 回 调 方 法 赋 给 父 请 求 的 write_event_handler 指 针 (为 
什么 设置 write _event handler? 因为 父 请 求 正 处 于 等 竺 发送 啊 应 的 阶段 ， 详 见 11.7 节 ) ， 例 
如 : 





pr->write event handler = mytest post handler; 





mytest post_ handler 束 是 .6.4 节 中 实现 的 父 请 求 重新 激活 后 的 回调 方法 。 


在 5.6.3 市 中 可 以 看 到 相关 的 具体 例子 。 


5.4.3 ”处 理 父 请 求 被 重新 激活 后 的 回调 方法 





mytest post handler 是 父 请 求 重新 激活 后 的 回调 方法 ， 它 对 应 于 ngx_http_event handler pt 
指针 ， 如 下 所 示 : 





typedef void (*ngx http event handler pt) (ngx http request t *r); 
struct ngx http request s { 


ngx http event handler pt write event handler; 





这 个 方法 负责 发 送 响应 包 给 用 户 ， 其 流程 与 3.7 节 中 介绍 的 发 送 方式 是 一 致 的 ， 也 可 以 
参考 $.6.4 节 中 的 例子 。 


$.4.4 ”启动 subrequest 子 请 求 
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在 ngx_http_mytest_handler 处 理 方法 中 ， 可 以 启动 subrequest 子 请 求 。 首 先 调 用 
ngx http_ subrequest 方 法 建立 subrequest 子 请 求 ， 在 ngx http mytest handler 返 回 后 ，HTTP 框 架 
会 目 动 执行 子 请 求 。 先 看 一 下 ngx_http_ subrequest 的 定义 : 








ngx int t 

ngx http subrequest (ngx http request t *r, 
ngx str t uri, ngx str t args, ngx http request 七 **psr, 
ngx http post subrequest t *ps, ngx uint t flags); 





下 面 依次 介绍 ngx_http_subrequest 中 的 参数 和 返回 值 。 
(1) ngx http request t*r 
ngx_http_request_t*r 是 当前 的 请 求 ， 也 就 是 父 请 求 。 


(2) ngx_str_t*uri ngx_str_t*uri 是 子 请 求 的 URI， 它 对 究竟 选用 nginx.conf 配 置 文件 中 的 哪 
个 模块 来 处 理子 请 求 起 决定 性 作用 。 








(3) ngx str t*args 
ngx_str_t*args 是 子 请 求 的 URI 参 数 ， 如 果 没 有 参数 ， 可 以 传送 NULL 空 指针 。 
(4) ngx http request t**psr 


pst 是 输出 参数 而 不 是 输入 参数 ， 它 将 把 ngx http_ subrequest 生 成 的 子 请 求 传 出 来 。 一 
般 ， 我 们 先 建立 一 个 子 请 求 的 空 指针 ngx http request tspsr， 再 把 它 的 地 址 &psr 传 入 到 
ngx http subrequest 方 法 中 ， 如 果 ngx http subrequest 返 回 成 功 ，psr 就 指向 建立 好 的 子 请 求 。 


($5) ngx http post subrequest t*ps 


这 里 传 入 5.4.2 节 中 创建 的 ngx http post subrequest t 结 构 体 地 址 ， 它 指出 子 请 求 结束 时 必 
须 回调 的 处 理 方 法 。 
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(6) ngx uint tflags 


flag 的 取 值 范围 包括 : (D0。 在 没有 特殊 需求 的 情况 下 都 应 该 填写 它 ; 
CNGX HTTP SUBREQUEST IN MEMORY。 这 个 宏 会 将 子 请 求 的 subrequest_ in memory 标 志 
位 置 为 1， 这 意味 着 如 果子 请 求 使 用 upstream 访 问 上 游 服 务 器 ， 那 么 上 游 服 务 器 的 响应 都 将 会 
在 内 存 中 处 理 ;， (BONGX _ HTTP SUBREQUEST WAITED。 这 个 宏 会 将 子 请 求 的 waited 标 志 位 
置 为 1， 当 子 请 求 提 前 结束 时 ， 有 个 done 标 志 位 会 置 为 1， 但 目前 HTTP 框 架 并 没有 针对 这 两 
个 标志 位 做 任何 实质 性 处 理 。 注 意 ，flag 是 按 比 特 位 操作 的 ， 这 样 可 以 同时 含有 上 述 3 个 值 。 








(7) 返回 值 
返回 NGX_OK 表 示 成 功 建立 子 请 求 ， 返回 NGX_ERROR 表 示 建 立 子 请 求 失 败 。 


ngx_http_mytest_handler 处 理 方法 的 返回 值 依 然 与 upstream 机 制 相 同 ， 它 也 必须 返回 
NGX_DONE， 原 因 也 是 相同 的 。 
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5.5 ”subrequest 执 行 过 程 中 的 主要 场景 





在 使 用 subrequest 时 ， 需 要 了 解 下 面 3 个 场景 : 
. 启动 subrequest 后 子 请 求 是 如 何 运 行 的 。 
` 子 请 求 如 何 存放 接收 到 的 响应 。 
. 子 请 求 结束 时 如 何 回调 处 理 方法 ， 以 及 激活 父 请 求 的 处 理 方法 。 


下 面 根据 序列 图 来 说 明 这 3 个 场景 。 


5.5.1 ”如 何 启 动 subrequest 


处 理 父 请 求 的 过 程 中 会 创建 子 请 求 ， 在 父 请 求 的 处 理 方法 返回 NGX_DONE 后 ，HTTP 框 
架 会 开始 执行 子 请 求 ， 如 图 5-6 所 示 。 


下 面 简单 介绍 一 下 图 $-6 中 的 每 一 个 步骤 : 





1) Nginx 主 循环 中 会 定期 地 调用 事件 模块 ， 检 查 是 否 有 网 络 事件 发 生 。 
2) 事件 模块 发 现 这 个 请 求 的 回调 方法 属于 HTTP 框 架 ， 交 由 HTTP 框 架 来 处 理 请 求 。 


3) 根据 解析 完 的 URI 来 决定 使 用 哪个 location 下 的 模块 来 处 理 这 个 请 求 。 
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| 


1. 检 查 是 奋 有 网 络 事件 






| 
We 3. 检查 location 时 发 现 应 由 mytest 模 块 处 理 


4. 调用 mytest 模块 的 处 理 方法 











| 
| 
| 
| 
| 
S$: I 的 URI 和 回调 方 i 


6 .调用 ngx_http _sub_request | Lm 


Ey 7. 将 子 请 求 添加 到 原始 请 求 的 posted _requests 链表 


I 
| 
| 
| 
| 
深 
| 
8 subrequest 参数 即 返 
ee | 
| 
| 
| 
Ne | 
| 
| 
~ 
| 
| 


>10. 由 于 具有 


Wi 请 求 , 所 以 继续 处 理子 请 求 





发 理 模块 处 理 


本 
| 


| 
12 .调用 反 向 代理 模块 的 入 口 方法 来 处 理子 请 求 
一 一 一 






13 .返回 NGX_DONE 


1 再次 检查 ， 发 现 当前 请 求 没 有 其 他 子 请 求 
次 给 事件 可 


16 本 次 网 络 事件 处 理 完 | 
nn ‘ci RN | 
| | | 


i ee ee et 


图 5-6 ”subrequest 的 启动 过 程序 列 图 
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4) 调用 mytest 模 块 的 ngx http_ mytest handler 方 法 处 理 这 个 请 求 。 


5) 设置 Subrequest 子 请 求 的 URI 及 回调 方法 ， 这 一 步 以 及 下 面 的 第 6~9 步 所 做 的 工作 参见 
5.4.4 节 。 


6) 调用 ngx _http_ subrequest 方 法 创建 子 请 求 。 


7) 创建 的 子 请 求 会 添加 到 原始 请 求 的 posted_requests 链 表 中 ， 这 样 保证 第 10 步 时 会 在 父 
请 求 返回 NGX_DONE 的 情况 下 开始 执行 子 请 求 。 


8) ngx_http_subrequest 方 法 执行 完毕 ， 子 请 求 创 建成 功 。 


9) ngx_http_mytest_handler 方 法 执行 完毕 ， 返 回 NGX_DONE， 这 样 父 请 求 不 会 被 销毁 ， 
将 等 竺 以 后 的 再 次 激活 。 


10) HTTP 框 架 执 行 完 当 前 请 求 〈 父 请 求 ) 后 ， 检 查 posted_ requests 链 表 中 是 否 还 有 子 请 
求 ， 如 果 存 在 子 请 求 ， 则 调用 子 请 求 的 write_event handler 方 法 《〈 详 见 11.7 节 ) 。 





11) 根据 子 请 求 的 URI (第 5 步 中 建立 ) ， 检 查 nginx.conf 文 件 中 所 有 的 location 配 置 ， 确 
定 应 由 哪个 模块 来 执行 子 请 求 。 在 本 章 的 例子 中 ， 子 请 求 是 交 由 反问 代理 模块 执行 的 。 








12) 调用 反 癌 代理 模块 的 入 口 方法 ngx_http proxy handler 来 处 理子 请 求 。 


13) 由 于 反 向 代理 模块 使 用 了 upstream 机 制 ， 所 以 它 也 要 通过 许多 次 的 异步 调用 才能 完 
整地 处 理 完 子 请 求 ， 这 时 它 的 入 口 方法 会 返回 NGX_ DONE (非常 类 似 $.1.5 节 中 的 内 容 ) 。 








14) 再 次 检查 是 人 否 还 有 子 请 求 ， 这 时 会 及 现 已 经 没有 子 请 求 需要 执行 了 。 当 然 ， 子 请 求 
可 以 继续 建立 新 的 子 请 求 ， 只 是 这 里 的 反 同 代理 模块 不 会 这 样 做 。 





15〉 当 第 2 步 中 的 网 络 读 取 事 件 处 理 完毕 后 ， 交 还 控制 权 给 事件 模块 。 
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5.5.2 ”如 何 转发 多 个 子 请 求 的 啊 应 包 体 


ngx_http_postpone_filter module 过 滤 模 块 实际 上 是 为 了 subrequest 功 能 而 建立 的 ， 本 草 的 
例子 虽然 没有 用 到 postpone (能 够 应 用 到 的 场合 其 实 非 常 少 ，， 这 里 还 是 要 介绍 一 下 这 个 过 
滤 模 块 希 望 解决 什么 样 的 问题 ， 这 样 读者 会 对 postpone 模 块 和 subrequest 则 的 关系 有 更 深刻 的 
了 解 。 


当 派 生 一 个 子 请 求 访问 第 三 方 服务 时 ， 如 末 只 是 希望 接收 到 完整 的 啊 应 后 在 Nginx 中 解 
析 、 处 理 ， 那 么 这 里 就 不 需要 postpone 模 块 ， 就 像 5.6 闻 中 的 例子 那样 处 理 即 可 ; 如 果 原 始 请 
求 派生 出 许多 子 请 求 ， 并 且 和 希望 将 所 有 子 请 求 的 啊 应 依次 转发 给 客户 器 ， 当 然 ， 这 里 的 “ 依 
次 ”就 是 按照 创建 子 请 求 的 顺序 来 发 送 响 应 ， 这 时 ，postpone 模 块 就 有 了 “用 武之 地 ”。Nginx 
中 的 所 有 请 求 都 是 异步 执行 的 ， 后 创建 的 子 请 求 可 能 优先 执行 ， 这 样 转发 到 客户 站 的 啊 应 就 
会 产生 混乱 。 而 postpone 模 块 会 强制 地 把 竺 转发 的 啊 应 包 体 放 在 一 个 链表 中 发 送 ， 只 有 优先 
转发 的 子 请 求 结束 后 才 会 开始 转发 下 一 个 子 请 求 中 的 啊 应 。 下 面 介绍 一 下 它 是 如 何 实现 的 。 




















每 个 请 求 的 ngx_http_request t 结 构 体 中 都 有 一 个 postponed 成 员 : 





struct ngx http request s { 


ngx http postponed request t *postponed; 





它 实 际 上 是 一 个 链表 : 





typedef struct ngx http postponed request s ngx http postponed request t; 
struct ngx http postponed request s { 


ngx http request t *request; 
ngx chain t out; 
ngx http postponed request t next; 


}; 
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从 上 述 代 码 可 以 看 出 ， 多 个 ngx_http postponed request t 之 间 使 用 next 指 针 连 接 成 一 个 单 
向 链表 。ngx_http postponed request t 中 的 out 成 员 是 ngx_chain tt 结构 ， 它 指向 的 是 来 自 上 游 
的 、 将 要 转发 给 下 游 的 啊 应 包 体 。 





每 当 使 用 ngx_http_output filter 方 法 《〈《 反 向 代理 模块 也 使 用 该 方法 转发 响应 ) 向 下 游 的 客 
户 端 发 送 响应 包 体 时 ， 都 会 调用 到 ngx http postpone filter module 过 滤 模 块 处 理 这 段 要 发 送 
的 包 体 。 下 面 看 一 下 过 滤 包 体 的 nex http postpone filter 方 法 〈 在 阅读 完 第 11 章 后 再 回头 看 这 
段 代 码 ， 概 念 可 能 会 更 加 清晰 ) : 











// 这 里 的 参数 


in 就 是 将 要 发 送 给 客户 端的 一 段 包 体 ， 第 


HTTP 过 滤 模 块 


static ngx int 七 
ngx http postpone filter(ngx http request t r, ngx chain t in) 
{ 


ngx connection 七 C7 
ngx http postponed request t pr; 
// Cc 是 


Nginx 与 下 游客 户 端 间 的 连接 ， 


c->data 保 存 的 是 原始 请 求 


C = Ir->connection; 


// 如 果 当 前 请 求 


r 是 一 个 子 请 求 《因为 





c->data 指 向 原始 请 求 ) 


if (r != c->data) { 


/* 如 果 待 发 送 的 
in 包 体 不 为 空 ， 则 把 


in 加 到 
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ngx http postponed request 七 结构 体 的 
out 链 表 中 ， 同 时 返回 


NGX_OK， 这 意味 着 本 次 不 会 把 


if (in) { 
ngx http postpone filter addl(r, in); 
return NGX OR; 
// 如 果 当 前 请 求 是 子 请 求 ， 而 
in 包 体 又 为 空 ， 那 么 直接 返回 即 可 
return NGX OK” 
} 
// 如 果 


postponed 为 空 ， 表示 请 求 


r 没 有 子 请 求 产 生 的 响应 需要 转发 


if (r->postponed == NULL) { 
/* 直 接 调 用 下 一 个 


HTTP 过 滤 模 块 继续 处 理 


in 包 体 即 可 。 如 果 没 有 错误 的 话 ， 就 会 开始 向 下 游客 户 端 发 送 响应 


if (in || c->buffered) { 
return ngx http next filter(r->main, in); 
# 
return NGX OK7 
} 
至 此 ， 说 明 


Postponeqd 链 表 中 是 有 子 请 求 产生 的 响应 需要 转发 的 ， 可 以 先 把 
in 包 体 加 到 待 转发 响应 的 末尾 


EE) .1 
ngx http postpone filter addl(r, in); 


} 
// 循环 处 理 


postponed 链 表 中 所 有 子 请 求 待 转发 的 包 体 
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QQG { 
pr = r->postponed; 


/* 如 果 


pr->request 是 子 请 求 ， 则 加 入 到 原始 请 求 的 


起 


posteqd requests 队 列 中 ， 等 待 


HTTP 框 架 下 次 调用 这 个 请 求 时 再 来 处 理 ( 参 见 


11.7 节 ) 


wf 
if (pr->request) { 
r->postponed = pr->next; 
c->data = pr->request; 
return ngx http post request (pr->request, NULL); 
} 
7/ 再 用 下 二 小 


HTTP 过 滤 模 块 转发 


out 链 表 中 保存 的 待 转发 的 包 体 


if (pr->out == NULL) { 
} else { 
if (ngx http next filter(r->main, pr->out) == NGX ERROR) { 





return NGX ERROR; 





postponed 链 表 


r->postponed = pr->next; 
} while (r->postponed); 
return NGX OK; 








图 5-7 展 示 了 使 用 反问 代理 模块 转发 子 请 求 的 包 体 的 一 般 流程 ， 其 中 的 第 5 步 正 是 上 面 介 
绍 的 ngx http postpone filter 方 法 。 


下 面 简单 地 介绍 一 下 图 5-7 中 的 每 一 个 步 又 : 





1) Nginx 主 循环 中 会 定期 地 调用 事件 模块 ， 检 查 是 否 有 网 络 事件 友 生 。 


2) 事件 模块 发 现 这 个 请 求 的 回调 方法 属于 反问 代理 模块 的 接收 HTTP 包 体 阶段 ， 于 是 交 


i 





3) 读 取 上 游 服 务 器 友 来 的 包 体 。 





4) 对 于 接收 到 的 字符 流 ， 会 依次 调用 所 有 的 HTTP 过 滤器 模块 来 转发 包 体 。 其 中 ， 还 会 
调用 到 postpone 过 小 模块 ， 这 个 模块 将 会 处 理 设置 在 子 请 求 中 的 ngx_http_postponed request t 
链表 。 


5) postpone 模 块 使 用 ngx_http_postpone_filter 方 法 将 待 转发 的 包 体 以 合适 的 顺序 再 进行 整 
理发 送 到 下 游客 户 端 。 如 果 ngx http postpone filter 方 法 没有 通过 ngx http next filter 方法 继续 
调用 其 他 HTTP 过 滤 模 块 〈 如 由 于 顺序 的 原因 而 暂停 转发 某 个 子 请 求 的 响应 包 体 ) ， 将 会 直 
接 跳 到 第 7 步 ， 否 则 继续 处 理 这 段 接收 到 的 包 体 〈 第 6 步 ) 。 


postpone 过 滤 模 块 










| < a pk 4 
| 1. 检查 是 否 有 网 络 事件 
| ， te fT -| 
2. 回调 当前 读 事 件 的 处 理 方法 


pw 3. 读 取 上 游 发 来 的 响应 


4. 这 用 postpone 过 小 模块 处 理 接收 到 上 的 : 六 -人行 0 到 


=>: > 5 恨 据 当前 子 请 求 的 状态 来 调整 待 转发 的 响应 包 体 


.继续 调用 其 他 过 滤 需 ， 全 部 执行 完 后 返回 
ce 









小 


7. 交还 控制 权 给 事件 模块 


nnnnunnnnnnr ne 





图 5-7 子 请 求 转发 HTTP 包 体 过 程 的 序列 图 


6) 继续 调用 其 他 HITTP 过 滤 模 块 ， 待 所 有 的 过 滤 模 块 执行 完毕 后 将 控制 权 交 还 给 反 向 代 
理 模 块 。 


7) 当 第 2 步 中 的 网 络 读 取 事件 处 理 完毕 后 ， 交 还 控制 权 给 事件 模块 。 


8) 当 本 轮 网 络 事件 处 理 完毕 后 ， 交 还 控制 权 给 Nginx 主 循环 。 


5.5.3 ” 子 请 求 如 何 激活 父 请 求 


子 请 求 在 结束 前 会 回调 在 ngx http post subrequest t 中 实现 的 handler 方 法 〈 见 $.4.2 节 ) ， 
在 这 个 handler 方 法 中 ， 又 设置 了 父 请 求 被 激活 后 的 执行 方法 mytest_post_handler， 流 程 如 图 5- 
8 所 示 。 


下 面 简单 地 介绍 一 下 图 5-8 中 的 每 一 个 步 又 : 





1〉Nginx 主 循环 中 会 定期 地 调用 事件 模块 ， 检 查 是 否 有 网 络 事件 发 生 。 


2) 如 果 事 件 模块 检测 到 连接 关闭 事件 ， 而 这 个 请 求 的 处 理 方法 属于 upstream 模 块 ， 则 交 
由 upstream 模 块 来 处 理 请 求 。 


3 ) upstream 模 块 开 始 调 用 ngx http upstream finalize request 方 法 来 结束 upstream 机 制 下 的 
请 求 〈 详 见 12.9 节 ) 。 
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Nginx 主 循环 





HTTP 框 架 | 反 向 代理 &upstream 模 块 


| 
1. 检 查 是 否 有 网 络 事件 








2. 回 调 当 前 连接 关闭 事件 的 处 理 函 数 


| 

| 

| 

| 

| 

| 

| 

| 

| 
4 . finalize 销毁 子 请 求 

| 
5. 回调 子 请 求 的 处 理 方法 








| 


6. 解 析 子 请 求 的 响应 , 并 设置 父 请 求 的 回调 方法 
Fk 
| 
| 


8. finalize 执行 完毕 
yy 





| 
> 10. 构造 向 用 户 发 送 的 响应 包 
| 


11. 调 用 发 送 方法 将 啊 应 发 给 客户 端 





| 14. 事件 处 理 完毕 
人 
| 15. 本 次 网 络 事件 处 理 完毕 | 

FD wo og me A 
| | 


图 5-8 子 请 求 激活 父 请 求 过 程 的 序列 图 


4) 调用 HTTP 框 架 提供 的 ngx http finalize request 方 法 来 结束 子 请 求 。 











5) ngx_http_finalize request 方法 会 检查 当前 的 请 求 是 否 是 子 请 求 ， 如 采 是 子 请 求 ， 则 会 
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回调 post_subrequest 成 员 中 的 handler 方 法 (参见 图 11-26 中 的 第 5 步 ) ， 也 就 是 会 调用 


mytest Subrequest post handler 方 法 〈 见 5.6.3 节 ) 。 





6) 在 实现 的 子 请 求 回调 方法 中 ， 解 析 子 请 求 返 回 的 响应 包 。 注 意 ， 这 时 需要 
write_event handler 设 置 父 请 求 被 激活 后 的 回调 方法 (因为 此 时 父 请 求 的 回调 方法 已 经 被 
HTTP 框 架设 置 为 什么 事 都 不 做 的 ngx http request empty handler 方 法 ， 详 见 第 11 章 ) 。 


7) 子 请 求 的 回调 方法 执行 完毕 后 ， 交 由 HTTP 框 架 的 ngx http finalize request 方 法 继续 向 
下 执行 


8) ngx_http finalize request 方 法 执行 完毕 。 











9) HTTP 框 架 如 果 发 现 当 前 请 求 后 还 有 父 请 求 需要 执行 ， 则 调用 父 请 求 的 
write_ event handler 回 调 方 法 。 








10) 这 里 可 以 根据 第 6 步 中 解析 子 请 求 啊 应 后 的 结果 来 构造 啊 应 包 。 


11) 调用 无 阻塞 的 nex http send header、ngx http output filter 发送 方法 ， 向 客户 端 发 送 
啊 应 包 。 


12) 无 阻 室友 送 方法 会 立刻 返回 。 即 使 目前 未 发 送 完 ，Nginx 之 后 也 会 异步 地 发 送 完 所 
有 的 啊 应 包 ， 然 后 再 结束 请 求 。 


13) 父 请 求 的 回调 方法 执行 完毕 。 





14) 当 第 2 步 中 的 上 游 服 务 占 连接 关闭 事件 处 理 完毕 后 ， 交 还 控制 权 给 事件 模块 。 


15) 当 本 轮 网 络 事件 处 理 完毕 后 ， 交 还 控制 权 给 Nginx 主 循环 。 
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5.6 ”subrequest 使 用 的 例子 


下 面 以 一 个 简单 的 例子 说 明 subrequest 的 用 法 。 场 景 很 简单 ， 当 使 用 浏览 器 访问 /query? 
s_sh000001 时 〈s_sh000001 是 新 浪 服务 器 上 的 A 股 上 证 指数 ) ，Nginx 由 mytest 模 块 处 理 ， 它 会 
生成 一 个 子 请 求 ， 由 反 向 代理 模块 处 理 这 个 子 请 求 ， 访 问 新 浪 的 http://hq.sinajs.cn 服务 器 ， 
这 时 子 请 求 得 到 的 响应 包 是 上 证 指数 的 当天 价格 交易 量 等 信息 ， 而 mytest 模 块 会 解析 这 个 响 
应 ， 重 新 构造 发 往 客户 端 浏 览 器 的 HTTP 响 应 。 浏 览 器 得 到 的 返回 值 格式 为 : stock[ 上 证 指 
数 ]，Today current price:2373.436,volumn:770。 当 然 ， 如 果 传 入 的 参数 不 仅 是 s sh000001， 也 
可 以 是 任意 新 浪 服 务 器 识别 的 股票 代码 ， 如 s_sh000009 代 表 上 证 380。 








这 个 例子 说 明 如 何 生成 子 请 求 ， 以 及 子 请 求 如 何 通过 配置 文件 配置 为 反 回 代理 服务 器 以 
访问 新 浪 ， 并 试图 将 新 浪 的 返回 内 容 全 部 保存 在 一 块 内 存 缓冲 区 中 ， 最 后 解析 绥 冲 区 中 的 内 
容 生 成 HTTP 啊 应 返回 给 浏览 器 等 过 程 。 这 里 的 限制 条 件 是 内 存 缓冲 区 的 大 小 要 可 以 容纳 完 
整 的 新 浪 服务 器 的 响应 ， 它 实际 上 是 由 ngx_http_upstream conf t 结 构 体 内 的 buffer_size 参 数 决 
定 的 ( 见 5.3.1 市 )， 而 对 于 反问 代 理 模 块 来 说 ， 就 是 由 nginx.conf 文 件 中 的 proxy_buffer_size 
配置 项 决定 的 。 如 果 新 浪 这 样 的 上 游 服 务 占 返回 的 HTTP 响 应 大 于 缓冲 区 大 小 ， 请 求 将 会 出 
错 ， 这 时 要 么 增 大 proxy_buffer_size 配 置 的 值 ， 要 么 不 能 再 选择 反 向 代理 模块 访问 上 游 服 务 
如 ， 而 要 自己 使 用 upstream 机 制 编写 相应 的 HTTP 模 块 解析 上 游 服 务 占 的 啊 应 包 体 。 














5.6.1 配置 文件 中 子 请 求 的 设置 


若 访 问 新 浪 服务 器 的 URIL 为 /list=s_sh000001， 则 可 以 这 样 配 置 : 
location /list { 


// 决定 访问 的 上 游 服务 器 地 址 是 
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hdq.sina]js .cn 


proxy pass. ttps/Yha. sinals.en 


// 不 希望 第 三 方 服 务 发 来 的 


HTTP 包 体 进行 过 


gzip 压 缩 





proxy set header Accept-Encoding ""; } 








当然 ， 处 理 以 /query 开 头 的 URJI 用 户 请 求 还 需 选 用 mytest 模 块 ， 例 如 ; 





location /query { 


mytest; 





562 傅 求 上 上下文 





这 里 的 上 下 文 仅 用 于 保存 子 请 求 回调 方法 中 解析 出 来 的 股票 数据 ， 如 下 所 示 : 





typedef struct { 


PE nn 人 hn http: / /waw |i nuxporobe. con 





} ngx http mytest ctx 七 








新 浪 服 务 串 的 返回 大 致 如 下 : 





var hq str s sh000009=" 上 证 


38073356.3557;=5,7257=0.L7;266505; 2519967"; 





上 段 代码 中 引号 内 的 6 项 值 《以 运 号 分 隔 ) 就 是 解析 出 的 值 。 在 父 请 求 的 回调 方法 中 ， 
将 会 用 到 这 6 个 值 。 


5.6.3 ”了 于 请 求 结束 时 的 处 理 方法 


定义 mytest Subrequest post handler 作 为 子 请 求 结束 时 的 回调 方法 ， 如 下 所 示 : 





static ngx int t mytest subrequest post handler (ngx http request t *r, void *data, ngx int t rc){ 


// 当前 请 求 


Parent 成 员 指 向 父 请 求 


ngx http _ request t *pr = r->parent; /* 注 意 ， 由 于 上 下 文 是 保存 在 父 请 求 中 的 (参见 
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5.6.5 节 ) ， 所 以 要 由 


PT 取 上 下 文 。 其 实 有 更 简单 的 方法 ， 即 参数 


data 就 是 上 下 文 ， 初 始 化 


subrequest 时 就 对 其 进行 设置 。 这 里 仅 为 了 说 明 如 何 获取 到 父 请 求 的 上 下 文 


*/ 


ngx http mytest ctx t* myctx = ngx http get module ctx(pr,ngx http mytest module); pr->headers out.status = 








NGX_HTTP_OK (也 就 是 


200) ， 则 意味 着 访问 新 浪 服务 器 成 功 ， 接 着 将 开始 解析 


HTTP 包 体 
发 内 


if (r->headers out .status == NGX HTTP OK) { 


/* 在 不 转发 响应 时 ， 


buffer 中 会 保存 上 游 服务 器 的 响应 。 特 别 是 在 使 用 反 向 代理 模块 访问 上 游 服务 器 时 ， 如 果 它 使 用 
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upstream 机 制 时 没有 重 定义 


input filter 方 法 ， 


upstream 机 制 默 认 的 


input filter 方 法 会 试图 把 所 有 的 上 游 响 应 全 部 保存 到 


buffer 缓 冲 区 中 
*/ 


ngx buf tx pRecvBuf = &r->upstream->buffer; /* 以 下 开始 解析 上 游 服务 器 的 响应 ， 并 将 解析 出 的 值 赋 到 上 下 文 结构 体 


myctx->stock 数 组 中 
*/ 
for (;pRecvBuf->pos != pRecvBuf->last; pRecvBuf->pos++) { 
if (*pRecvBuf->pos == ',' || *pRecvBuf->pos == "'\"™') { 


if (flag > 0) 


myctx->stock[flag-1] .len = pRecvBuf->pos-myctx->stock[flag-1] .data; } 


flagt++; 
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myctx->stock[flag-1] .data = pRecvBuf->pos+l; } 


if (flag > 6) 


break; 


// 设置 接 下 来 父 请 求 的 回调 方法 ， 这 一 步 很 重要 


pr->write event handler = mytest post handler; return NGX OK， 





5.6.4” 父 请 求 的 回调 方法 


将 父 请 求 的 回调 方法 定义 为 mytest_post_handler， 如 下 所 示 : 





static void mytest post handler (ngx http request t *r) { 


// 如 果 没 有 返回 


200， 则 直接 把 错误 码 发 回 用 户 


if (r->headers out.status != NGX HTTP OK) { 


ngx http finalize request(r, r->headers out.status); return; 


中 THNNNNNDDD htt p: // www | i nuxprobe. con 





// 当前 请 求 是 父 请 求 ， 直 接 取 其 上 下 文 


ngx http mytest ctx tx myctx = ngx http get module ctx(r,ngx http mytest module); /* 定 义 发 给 用 户 的 








HTTP 包 体内 容 ， 格 式 为 : 


StoOGkl[s 


],Today current price: 


; Volumn: 
4 


ngx str t output format = ngx string("stock[%V],Today current price: ®%V, volumn: %V"); // 计算 待 发 送 包 体 的 长 度 


int bodylen = output format.len + myctx->stock[0] .len +t+myctx->stock[1].lentmyctx->stock[4] .len-6; r->header: 


ngx buf tx b = ngx create temp buf(r->pool, bodylen); ngx snprintf (b->pos, bodylen, (char*)output format.da 
b->last buf = 1; 


ngx chain t out; 


村 :* 耻 - 卫 由 由 所 所 由 所 由  http://wWw linuxorobe. con 





out .next = NULL; 


// 设置 


Content-Type， 注 意 ， 在 汉字 编码 方面 ， 新 浪 服务 器 使 用 了 


GBK 





Static ngx str t type = ngx string("text/plain; charset=GBK"); r->headers out.content type = type; r->heade: 


ngx http finalize request 结 束 请 求 ， 因 为 这 时 


HTTP 框 架 不 会 再 帮忙 调用 它 


发/ 


ngx http finalize request(r, ret); 





5.6.5 ”启动 subrequest 


在 处 理 用 户 请 求 的 ngx http mytest handler 方 法 中 ， 开 始 创建 subrequest 子 请 求 。 
ngx_http_mytest_handler 方 法 的 完整 实现 如 下 所 示 : 





static ngx int t 


ngx http mytest handler (ngx http request t *r) { 


作 加 中 http://wWw |1 nuxorobe. con 





用 下 妆 


ngx http mytest ctx tx myctx = ngx http get module ctx (rngx http mytest module); if (myctx == NULL) 








myctx = ngx palloc(r->pool, sizeof (ngx http mytest ctx t)); if (myctx == NULL) 








return NGX ERROR; 


// 将 上 下 文 设置 到 原始 请 求 


ngx http set ctx(r,myctx,ngx http mytest module); } 


// ngx http post subrequest 七 结构 体会 决定 子 请 求 的 回调 方法 ， 参 见 


ngx http post subrequest t *psr = ngx palloc(r->pool, sizeof (ngx http post subrequest t+)); if (psr == NULL) 
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return NGX HTTP INTERNAL SERVER ERROR; } 


// 设置 子 请 求 回调 方法 为 


mytest subrequest post handler 


psr->handler = mytest subrequest post handler; /* 将 


data 设 为 


myctx 上 下 文 ， 这 样 回调 


mytest subrequest post handler 时 传 入 的 


data 参 数 就 是 


myctx*/ 
psr->data = myctx; 


/* 子 请 求 的 


URI 前 级 是 


/1ist， 这 是 因为 访问 新 浪 服务 器 的 请 求 必须 是 类 似 
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/list=s _ sh000001 的 


URI， 这 与 在 


nginx.conf 中 配置 的 子 请 求 


location 的 


URI 是 一 致 的 ( 见 


2 


ngx str 七 Sub prefix = ngx string("/list="); ngx str t sub location; 


sub location.len = Sub prefix.len + r->args.len; sub location.data = ngx palloc(r->pool, sub location.len); 


ngx http request t *sr; 


/* 调 用 


ngx_ http subrequest 创 建 子 请 求 ， 它 只 会 返回 
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NGX_OK 或 者 


NGX_ERROR。 返 回 





NGX OK 时 ， 


SI 已 经 是 合法 的 子 请 求 。 注 意 ， 这 里 的 














攻 





NGX_HTTP SUBREOUEST IN _ MEMORY 参数 将 告诉 


upstream 模 块 把 上 游 服 务 器 的 响应 全 部 保存 在 子 请 求 的 


sr->upstream->buffer 内 存 缓冲 区 中 


*/ 





ngx int t rc = ngx http subrequest(r, &sub location, NULL, &sr, psr, NGX HTTP SUBREQUEST IN MEMORY); IE (rc 

















return NGX ERROR; 


// 必须 返回 





NGX DONE， 原因 同 


upstream 
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return NGX DONE; 





至 此 ， 一 个 使 用 subrequest 的 mytest 模 块 已 经 创建 完成 ， 它 支持 的 并 发 HTTP 连 接 数 只 与 物 
理 内 存 大 小 相关 ， 因 此 ， 这 样 的 服务 器 通常 可 以 轻易 地 文 持 几 十 万 的 并 发 TCP 连 接 。 
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7 We 


反问 代理 是 Nginx 和 希望 实现 的 一 大 功能 。 从 本 章 的 内 容 中 可 以 感受 到 ，upstream 和 
subrequest 都 为 转发 上 游 服务 器 的 啊 应 做 了 大 量 工作 ， 当 然 ，upstream 的 转发 过 程 也 非常 
效 。 然 而 ， 转 发 啊 应 毕竟 只 是 访问 第 三 方 服 务 的 一 种 应 用 ， 而 upstream 最 初始 的 目的 就 是 用 
于 访问 上 游 服务 器 。 本 章 前 半 部 分 虽然 以 转发 啊 应 为 例 说 明了 upstream 的 一 种 使 用 方式 ， 但 
后 半 部 分 创建 的 子 请 求 却 是 通过 反 辐 代理 模块 使 用 upstream 将 上 游 服务 器 简单 地 保存 在 内 存 
中 的 。 关 于 upstream 更 详细 的 用 法 ， 将 在 第 12 章 讲述 。subrequest 是 分 解 复杂 请 求 的 设计 方 
法 ， 派 生出 的 子 请 求 使 用 某 些 HTTP 模 块 基于 upstream 访 问 第 三 方 服务 是 最 常见 的 用 法 。 通 过 
subrequest 可 以 使 Nginx 在 保持 高 并 发 的 前 提 下 处 理 复杂 的 业务 。 











当 应 用 需要 访问 第 三 方 服务 时 ， 可 以 根据 以 上 特性 选择 使 用 upstream 或 者 subrequest， 它 
们 可 以 完全 地 发 挥 Nginx 原 生 的 高 并 发 特性 ， 支 持 现 代 互 联网 服务 器 中 海量 数据 的 处 理 。 
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第 6 革 开发 一 个 简 早 的 HTTP 过 渡 模 块 


本 章 开 始 介 绍 如何 开 发 HTTP 过 滤 模 块 。 顾 名 思 义 ，HTTP 过 小 模 块 也 是 一 种 HTTP 模 
块 ， 所 以 第 3 章 中 讨论 过 的 如 何 定 义 一 个 HTTP 模 块 以 及 第 4 章 中 讨论 的 使 用 配置 文件 、 上 下 
文 、 日 志 的 方法 对 它 来 说 都 是 适用 的 。 事 实 上 ， 开 发 HTTP 过 滤 模 块 用 到 的 大 部 分 知识 在 第 3 
章 和 第 4 章 中 都 已 经 介绍 过 了 ， 只 不 过 ，HTTP 过 滤 模 块 的 地 位 、 作 用 与 正常 的 HTTP 处 理 模 
块 是 不 同 的 ， 它 所 做 的 工作 是 对 发 送 给 用 户 的 HTTP 响 应 包 做 一 些 加 工 。 在 6.1 节 和 6.2 节 中 将 
会 介绍 默认 编译 进 Nginx 的 官方 HTTP 过 滤 模 块 ， 从 这 些 模块 的 功能 上 就 可 以 对 比 出 HTTP 过 
滤 模 块 与 HITP 处 理 模 块 的 不 同 之 处 。HTTP 过 滤 模 块 不 会 去 访问 第 三 方 服务 ， 所 以 第 $ 章 中 
介绍 的 upstream 和 subrequest 机 制 在 本 章 中 都 不 会 使 用 到 。 














实际 上 ， 在 阅读 完 第 3 音 和 第 4 章 内 容 后 再 来 学 习 本 章 内 容 ， 相 信 读 者 会 发 现 开 及 HTTP 
过 小 模块 是 一 件 非 常 简单 的 事情 。 在 6.4 节 中 ， 我 们 通过 一 个 简单 的 例子 来 演示 如 何 开 友 


HTTP 过 滤 模 块 。 
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6.1 过渡 模 块 的 意义 


HTTP 过 滤 横 块 与 普通 HTTP 模块 的 功能 是 完全 不 同 的 ， 下 面 先 来 回顾 一 下 普通 的 HITP 
模块 有 何 种 功能 





HTTP 框 架 为 HTTP 请 求 的 处 理 过 程 定义 了 11 个 阶段 ， 相 关 代 码 如 下 所 示 : 





typedef enum { 































































































NGX HTTP POST READ PHASE = 0, 
NGX HTTP SERVER REWRITE PHAS 
NGX HTTP FIND CONFIG PHAS 
NGX HTTP REWRITE PHASE, 

NGX HTTP POST REWRITE PHAS 
NGX HTTP PREACCESS PHAS 

NGX HTTP ACCESS PHASE, 

NGX HTTP POST ACCESS PHASE, 
NGX HTTP TRY FILES PHASE, 
NGX HTTP CONTENT PHASE, 

NGX HTTP LOG PHASE 
































} ngx http phases; 





HTTP 框 架 人 允许 普 通 的 HTTP 处 理 模 块 介入 其 中 的 7 个 阶段 处 理 请 求 ， 但 是 通常 大 部 分 
HTTP 模 块 〈( 官 方 模块 或 者 第 三 方 模块 都 只 ead 
求 。 在 这 一 阶段 处 理 请 求 有 一 个 特点 ， 即 HTTP 模 块 有 两 种 介入 方法 ， 第 一 种 方法 是 ， 任 一 
个 HTTP 模 块 会 对 所 有 的 用 户 请 求 产 生 作 用 ， 第 二 种 方法 是 ， 只 对 请 求 的 URI 匹 配 了 nginx.conf 
中 某 些 location 表 达 式 下 的 HITP 模 块 起 作用 。 就 像 第 3 章 中 定义 的 mytest 模 块 一 样 ， 大 部 分 模 
块 都 使 用 上 述 的 第 二 种 方法 处 理 请 求 ， 这 种 方法 的 特点 是 一 种 请 求 仅 由 一 个 HTTP 模 块 〈 在 
NGX _HTITP_ CONTENT _ PHASE 阶段 ) 处 理 。 如 果 和 希望 多 个 HITP 模 块 共同 处 理 一 个 请 求 ， 则 
多 半 是 由 subrequest 功 能 来 完成 ， 即 将 原始 请 求 分 为 多 个 子 请 求 ， 每 个 子 请 求 再 由 一 个 HTTP 
模块 在 NGX HTTP CONTENT PHASE 阶 段 处 理 。 


然而 ，HTTP 过 滤 模 块 则 不 同 于 此 ， 一 个 请 求 可 以 被 任意 个 HTTP 过 滤 模 块 处 理 。 因 此 ， 
普通 的 HTTP 模 块 更 倾 同 于 完成 请 求 的 核心 功能 ， 如 static 模 块 负责 静态 文件 的 处 理 。HTTP 过 
滤 模 块 则 处 理 一 些 附 加 的 功能 ， 如 gzip 过 滤 模 块 可 以 把 发 送 给 用 户 的 静态 文件 进行 gzip 压 缩 
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处 理 后 再 发 出 去 ，image_ filter 这 个 第 三 方 过滤 模 块 可 以 将 图 片 类 的 静态 文件 制作 成 缩 略 图 。 
而 且 ， 这 些 过 滤 模 块 的 效果 是 可 以 根据 需要 车 加 的 ， 比 如 先 由 not_modify 过 滤 模 块 处 理 请 求 
中 的 浏览 器 缓存 信息 ， 再 交 给 range 过 滤 模 块 处 理 HTTP range 协 议 ( 支 持 断 点 续 传 )， 然 后 交 
由 gzip 过 滤 模 块 进行 压缩 ， 可 以 看 到 ， 一 个 请 求 经 由 各 HTTP 过 滤 模 块 流水 线 般 地 依次 进行 处 
ET 








HTTP 过 滤 模 块 的 另 一 个 特性 是 ， 在 普通 HTTP 模 块 处 理 请 求 完毕 ， 并 调用 
ngx_http Send _ header 发 送 HITTP 头 部 ， 或 者 调用 ngx_http_output filter 发 送 HTTP 包 体 时 ， 才 会 
由 这 两 个 方法 依次 调用 所 有 的 HTTP 过 小 模块 来 处 理 这 个 请 求 。 因 此 ，HTTP 过 小 模块 仪 处 理 
服务 器 发 往 客 户 端 的 HTTP 响 应 ， 而 不 处 理 客 户 端 发 往 服 务 器 的 HTTP 请 求 。 


Nginx 明 确 地 将 HTTP 响 应 分 为 两 个 部 分 : HTTP 头 部 和 HTTP 包 体 。 因 此 ， 对 应 的 HITP 过 
滤 模 块 可 以 选择 性 地 只 处 理 HTTP 头 部 或 者 HTTP 包 体 ， 当 然 也 可 以 三 者 皆 处 理 。 例 如 ， 
not modify 过 滤 模 块 只 处 理 HITP 头 部 ， 完 全 不 关心 htp 包 体 ， 而 gzip 过 滤 模 块 首先 会 处 理 
HTTP 头 部 ， 如 检查 浏览 器 请 求 中 是 否 文 持 gzip 解 压 ， 然 后 检查 啊 应 中 HTTP 头 部 里 的 Content- 
Type 是 否 属于 nginx.conf 中 指定 的 gzip 压 缩 类 型 ， 接 着 才 处 理 HITP 包 体 ， 针 对 每 一 块 buffsr 组 
冲 区 都 进行 gzip 压 缩 ， 这 样 再 交 给 下 一 个 HTTP 过 滤 模 块 处 理 。 
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6.2 ”过 小 模块 的 调用 顺序 


既然 一 个 请 求 会 被 所 有 的 HTTP 过滤 模块 依次 处 理 ， 那 么 下 面 来 看 一 下 这 些 HITP 过 滤 模 
块 是 如 何 组 织 到 一 起 的 ， 以 及 它们 的 调用 顺序 是 如 何 确定 的 。 


6.2.1 过 滤 链 表 是 如 何 构 成 的 


在 编译 Nginx 源 代码 时 ， 已 经 定义 了 一 个 由 所 有 HTTP 过 滤 模 块 组 成 的 单 链表 ， 这 个 单 链 
表 与 一 般 的 链表 是 不 一 样 的 ， 它 有 另类 的 风格 : 链表 的 每 一 个 元 素 都 是 一 个 独立 的 C 源 代码 
文件 ， 而 这 个 C 源 代码 文件 会 通过 两 个 static 静 态 指针 《分 别 用 于 处 理 HTTP 头 部 和 HTTP 包 
体 ) 再 指向 下 一 个 文件 中 的 过 滤 方 法 。 在 HTTP 框 架 中 定义 了 两 个 指针 ， 指 向 整个 链表 的 第 
一 个 元 素 ， 也 就 是 第 一 个 处 理 HTTP 头 部 、HTTP 包 体 的 方法 。 





这 两 个 处 理 HITTP 头 部 和 HTTP 包 体 的 方法 是 什么 样 的 昵 ? HTTP 框 架 进行 了 如 下 定义 : 





typedef ngx int 七 (xngx http output header filter pt) 
(ngx http request 七 r); 

typedef ngx int t (ngx http output body filter pt) 
(ngx http request t r, ngx chain t chain); 











如 上 所 示 ，ngx_http_output_ header filter pt 是 每 个 过 滤 模 块 处 理 HTTP 头 部 的 方法 原型 ， 
它 仅 接 收 1 个 参数 r， 也 就 是 当前 的 请 求 ， 其 返回 值 一 般 是 与 3.6.1 节 中 介绍 的 返回 码 通 用 的 ， 
如 NGX_ERROR 表 示 失 败 ， 而 NGX_OK 表 示 成 功 。 


ngx_http_output body _ filter_pt 是 每 个 过 滤 模 块 处 理 HITP 包 体 的 方法 原型 ， 它 接收 两 个 参 
数 一 r 和 chain， 其 中 + 是 当前 的 请 求 ，chain 是 要 发 送 的 HTTP 包 体 ， 其 返回 值 与 
ngx http output header filter pt 相同 。 








所 有 的 HTTP 过 滤 模 块 需要 实现 这 两 个 方法 (或 者 仅 实 现 其 中 的 一 个 也 是 可 以 的 ) 。 因 
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这 个 单 向 链表 是 围绕 着 每 个 文件 (也 就 是 HTTP 过 滤 模 块 ) 中 的 这 两 个 处 理 方法 来 建立 
的 ， 也 就 是 说 ， 链 表 中 的 元 素 实 际 上 就 是 处 理 方法 。 


先 来 看 一 下 HTTP 框 架 中 定义 的 链表 入 口 : 





extern ngx http output header filter pt ngx http top header filter; 
extern ngx http output body filter pt ngx http top body filter; 











当 执 行 npgx_http_send_header 发 送 HTTP 头 部 时 ， 束 从 ngx_http_top_header_filter 指 针 开 始 裔 
历 所 有 的 HITP 头 部 过 滤 模 块 ， 而 在 执行 ngx_http_output filter 发 送 HTTP 包 体 时 ， 就 从 
ngx http top body filter 指 针 开 始 遍 历 所 有 的 HITP 包 体 过 滤 模 块 。 下 面 来 看 一 下 在 Nginx 源 代 
码 中 是 如 何 做 的 : 





ngx int t 
ngx _ http send header (ngx http request 七 *r) 
{ 
if (r=>err status) { 
r->headers out.status = r->err status; 
r->headers out.status line.len = 0; 
} 
return ngx http top header filter (r); 





} 





在 发 送 HTTP 头 部 时 ， 从 ngx http top header filter 指 针 指 向 的 过 小 模块 开始 执行 。 而 发 送 
HTTP 包 体 时 都 是 调用 ngx _http output filter 方 法 ， 如 下 所 示 : 





ngx int 七 
ngx http output filter(ngx http request t r, ngx chain t in) 
{ 


ngx int t rc; 
ngx connection 七 *c; 
C = Ir->connection; 


rc = ngx http top body filterl(r, in); 
if (rc == NGX ERROR) { 
/* NGX_ERROR 可 能 由 任何 过 滤 模 块 返回 











yf 
Cc->error = 1; 
} 


return re; 








遍历 访问 所 有 的 HTTP 过 滤 模 块 时 ， 这 个 单 链表 中 的 元 素 是 怎么 用 next 指 针 连 接 起 来 的 
TT 让 人 人 人 位 人 位 Ce 





呢 ? 很 简单 ， 每 个 HTTP 过 滤 模 块 在 初始 化 时 ， 会 先 找 到 链表 的 首 元 素 

ngx http top header filter 指 针 和 ngx http top body filter 指 针 ， 再 使 用 static 静 态 类 型 的 

ngx http next header filter 和 ngx http next body filter 指 针 将 自己 插入 到 链表 的 首部 ， 这 样 就 
行 了 。 下 面 来 看 一 下 在 每 个 过 滤 模 块 中 ngx http next header filter 和 ngx http next body filter 
指针 的 定义 : 














static ngx http output header filter pt ngx http next header filter; 
static ngx http output body filter pt ngx http next body filter; 














注意 ，ngx http next header filter 和 ngx http next body filter 都 必须 是 static 静 态 变 量 ， 为 
什么 昵 ? 因 为 static 类 型 可 以 让 上 面 两 个 变量 仅 在 当前 文件 中 生效 ， 这 就 允许 所 有 的 HTTP 过 
滤 模块 都 有 各 自 的 ngx http next header filter 和 ngx http next body filter 指 针 。 这 样 ， 在 每 个 
HTTP 过 小 模块 初始 化 时 ， 就 可 以 用 上 面 这 两 个 指针 指向 下 一 个 HTTP 过 滤 模 块 了 。 例 如 ， 可 
以 像 下 列 代码 一 样 将 当前 HITP 过 滤 模 块 的 处 理 方法 添加 到 链表 首部 。 











ngx http next header filter = ngx http top header filter; 

ngx http top header filter = ngx http myfilter header filter; 
ngx http next body filter = ngx http top body filter; 

ngx http top body filter = ngx http myfilter body filter; 





























这 样 ， 在 初始 化 到 本 模块 时 ， 自 定义 的 ngx_http_myfilter_header filter 与 
ngx_http_myfilter_body filter 方 法 就 暂时 加 入 到 了 链表 的 首部 ， 而 且 本 模块 所 在 文件 中 static 类 
型 的 ngx http next header filter 指 针 和 ngx http next body filter 指 针 也 指向 了 链表 中 原来 的 首 
部 。 在 实际 使 用 中 ， 如 果 需 要 调用 下 一 个 HTTP 过 滤 模 块 ， 只 需要 调用 
ngx_http_next header filter(r) 或 者 ngx_http next body filter(r,chain) 就 可 以 了 。 





6.2.2 ”过滤 链 表 的 顺序 


HTTP 过 滤 模 块 之 间 的 调用 顺序 是 非常 重要 的 。 如 果 两 个 HTTP 过 滤 模 块 按 照相 反 的 顺序 
执行 ， 完 全 可 能 生成 两 个 不 同 的 HTTP 啊 应 包 。 例 如 ， 如 果 现 在 有 一 个 图 片 缩 略 图 过 滤 模 
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块 ， 还 有 一 个 图 片 裁 勇 过 滤 模 块 ， 当 返回 一 张 图 片 给 用 户 时 ， 这 两 个 模 英 的 执行 顺序 不 同 的 
话 就 会 导致 用 户 接收 到 不 一 样 的 图 片 。 


在 上 文中 提 到 过 ，Nginx 在 编译 过 程 中 就 会 决定 HITP 过 滤 模 块 的 顺序 。 这 件 事情 到 底 是 
怎样 发 生 的 昵 ? 这 其 实 与 3.3 节 中 所 说 的 普通 HTTP 模 块 的 顺序 是 一 样 的 ， 也 是 由 configure 生 
成 的 ngx modules 数 组 中 各 模块 的 顺序 决定 的 。 





由 于 每 个 HTTP 过 滤 模 块 的 初始 化 方法 都 会 把 自己 加 入 到 单 链表 的 首部 ， 所 以 ， 什 么 时 
候 、 以 何 种 顺序 调用 这 些 HTTP 过 滤 模 块 的 初始 化 方法 ， 将 会 决定 这 些 HTTP 过 滤 模 块 在 单 链 
表 中 的 位 置 。 


什么 时 候 开 始 调用 各 个 HITP 模 块 的 初始 化 方法 呢 ? 这 主要 取决 于 我 们 把 类 似 
ngx_http_myfilter_init 这 样 的 初始 化 方法 放 到 ngx_http_module t 结 构 体 的 哪个 回调 方法 成 员 中 。 
例如 ， 大 多 数 官方 HTTP 过 涯 模块 都 会 把 初始 化 方法 放 到 postconfiguration 指 针 中 ， 那 么 它 就 
会 在 图 4-1 的 第 6 步 将 当前 模块 加 入 到 过 小 链表 中 。 不 建议 把 初始 化 方法 放 到 
ngx_http_module_t 的 其 他 成 员 中 ， 那 样 会 导致 HTTP 过 滤 模 块 的 顺序 不 可 控 。 





初始 化 时 的 顺序 又 是 如 何 决 定 的 呢 ?” 首 先 回顾 一 下 第 1 章 的 相关 内 容 ， 在 1.7 节 中 ， 介 绍 
了 configure 命 令 生 成 的 ngx_modules.c 文 件 ， 这 个 文件 中 的 ngx_modules 数 组 会 保存 所 有 的 Nginx 
模块 ， 包 括 HTTP 普 通 模 块 和 HTTP 过 滤 模 块 ， 而 初始 化 Nginx 模 块 的 顺序 就 是 ngx_modules 数 
组 成 员 的 顺序 。 因 此 ， 只 需要 查看 configure 命 令 生成 的 ngx_modules.c 文 件 就 可 以 知道 所 有 
HTTP 过 滤 模 块 的 顺序 了 。 





由 此 可 知 ，HTTP 过 滤 模 块 的 顺序 是 由 configure 命 令 生成 的 。 当 然 ， 如 果 用 户 对 configure 
命令 生成 的 模块 顺序 不 满意 ， 完 全 可 以 在 configure 命 令 执 行 后 、make 编 译 命令 执行 前 修改 
ngx modules.c 文 件 的 内 容 ， 对 ngx modules 数 组 中 的 成 员 进 行 顺 序 上 的 调整 。 


@ ;i 对 于 HITP 过 滤 模 块 来 说 ， 在 ngx_modules 数 组 中 的 位 置 越 靠 后 ， 在 实际 执行 


尘 求 时 部 忆 风 和 居 生 加 兴 芷 宁 好 化 HITP 寺 起 革 亲 并 /邦人 中 沁 站 冯 尖 基尼 哲 入 





到 整个 单 链 表 的 首部 的 。 


configure 执 行 时 是 怎样 确定 Nginx 模 块 间 的 顺序 的 呢 ? 当 我 们 下 载 官 方 提 供 的 Nginx 源 代 
码 包 时 ， 官 方 提 供 的 HITP 过 滤 模 块 顺序 已 经 写 在 auto 目 录 下 的 modules 脚 本 中 了 。 图 6-1 描 述 
了 这 个 顺序 。 


如 果 在 执行 configure 命 令 时 使 用 --add-module 选 项 新 加 入 第 三 方 的 HTTP 过 滤 模 块 ， 那 么 
第 三 方 过 滤 模 块 会 处 于 ngx_modules 数 组 中 的 哪个 位 置 呢 ? 答案 也 可 以 在 图 6-1 中 找到 。 


如 图 6-1 所 示 ， 在 执行 configure 命 令 时 仅 使 用 --add-module 参 数 添加 了 第 三 方 HTTP 过 滤 模 
块 。 这 里 没有 把 默认 未 编译 进 Nginx 的 官方 HTTP 过 滤 模 块 考虑 进去 。 这 样 ， 在 configure 执 行 
完毕 后 ，Nginx 各 HTTP 过 滤 模 块 的 执行 顺序 就 确定 了 。 默 认 HTTP 过 滤 模 块 间 的 顺序 必须 如 
图 6-1 所 示 ， 因 为 它们 是 “ 写 死 "在 auto/modules 肢 本 中 的 。 读 者 可 以 通过 阅读 这 个 modules 脚 本 
的 源 代码 了 解 Nginx 是 如 何 根据 各 官方 过 滤 模 块 功能 的 不 同 来 决定 它们 的 顺序 的 。 对 于 图 6-1 
中 所 列 的 这 些 过 滤 模 块 ， 将 在 下 面 进行 简单 的 介绍 。 
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图 6-1 默认 即 编译 进 Nginx 的 官方 HTTIP 过 滤 模 块 与 第 三 方 HTTP 过 滤 模 块 间 的 顺序 


6.2.3 ”官方 默认 HTTP 过 滤 模 块 的 功能 简介 
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本 节 介 2 


表 6-1 


默认 即 编译 进 Nginx 的 HTTP 过 滤 模 块 


ngx_http not _ modified _ filter module 


ngx http_range body filter module 


ngx_http copy _filter module 


ngx_http_headers_filter module 


ngx_ http_userid filter module 


ngx_http_charset filter module 


ngx_http_ssi_ filter_ module 


ngx_http_postpone_ filter_ module 


ngx http gzip filter module 


ngx http_ range header filter module 


ngx http chunked filter module 


ngx http_header filter_ module 


ngx_http_ write_ filter module 


如 默认 即 编译 进 Nginx 的 HTTP 过 小 模块 的 功能 
读者 就 会 明白 图 6-1 列 出 的 HTTP 过 滤 模 块 间 的 排序 依据 是 什么 
行 后 的 模块 间 顺 序 不 满意 ， 就 可 以 正确 地 修改 这 些 过 小 模块 间 的 顺序 。 


默认 即 编译 进 Nginx 的 HTTP 


( 见 表 6-1) ， 通 过 对 它们 的 了 解 ， 
。 如 果 用 户 对 configure 命 令 执 


过 滤 模 块 


功 能 
仅 对 HTTP 头 部 做 处 理 。 在 返回 200 成 功 时 ， 根 据 请 求 中 IfModified- 
Since 或 者 IEUnmodified-Since 头 部 取得 浏览 器 缓存 文件 的 时 间 ， 再 分 析 


返回 用 户 文件 的 最 后 修改 时 间 ， 以 此 烘 定 是 否 直 接 发 送 304 Not Modified 
啊 应 给 用 户 

处 理 请 求 中 的 Range 信息 ， 根 据 Range 中 的 要 求 返 回 文件 的 一 部 分 给 
用 户 


仅 对 HTTP 包 体 做 处 理 。 将 用 户 发 送 的 ngx_chain t 结 构 的 HTTP 包 
体 复 制 到 新 的 ngx_chain t 结构 中 (都 是 各 种 指针 的 复制 ， 不 包括 实际 
HTTP 响应 内 容 )， 后 续 的 HTTP 过 滤 模 块 处 理 的 ngx_chain t 类 型 的 成 员 
都 是 ngx_http_copy_filter_module 模块 处 理 后 的 变量 

仅 对 HTTP 尖 部 做 处 理 。 人 允许 通过 修改 nginx.conf 配置 文件 ， 
给 用 户 的 响应 中 添加 任意 的 HTTP 头 部 

仅 对 HTTP 头 部 做 人 处理。 这 就 是 执行 configure 命令 时 提 到 的 http_ 
userid_module 模块 ， 它 基于 cookie 提供 了 简单 的 认证 管理 功能 

可 以 将 文本 类 型 返回 给 用 户 的 响应 包 ， 按 照 nginx.conf 中 的 配置 重新 
进行 编码 ， 再 返回 给 用 户 

支持 SSI ( Server Side Include， 
到 网 页 中 并 返回 给 用 户 

仅 对 HTTP 包 体 做 处 理 。5.5.2 节 详 细 介 绍 过 该 过 滤 模块 。 它 仅 应 用 于 
subrequest 产生 的 子 请 求 。 它 使 得 多 个 子 请 求 同 时 间 客 户 端 发 送 啊 应 时 能 
够 有 序 ， 所 谓 的 “有 序 ” 是 指 按照 构造 子 请 求 的 顺序 发 送 啊 应 

对 特定 的 HTTP 响应 包 体 (如 网 页 或 者 文本 文件 ) 进行 gzip 压缩 ， 再 
把 压缩 后 的 内 容 返 回 给 用 户 


在 返回 


服务 器 端 媒 人 人 ) 功能 ,将 文件 内 容 包 含 


支持 range 协议 

支持 chunk 编码 

仅 对 HTTP 头 部 做 处 理 。 该 过 滤 模 块 将 会 把 rc>headers out 结构 体 
中 的 成 员 序 列 化 为 返回 给 用 户 的 HTTP 响应 字符 流 ， 包 括 响 应 行 (如 


HTTP/1.1 200 OK) 和 啊 应 头 部 ， 并 通过 调用 ngx http_ write filter_ 
module 过 滤 模 块 中 的 过 滤 方 法 直接 将 HTTP 包头 发 送 到 客户 端 
仅 对 HTTP 包 体 做 处 理 。 该 模块 负责 向 客户 端 发 送 HTTP 响应 





从 表 6-1 中 可 以 了 解 到 这 些 默认 的 HTTP 过 滤 模 块 为 什么 要 以 图 6-1 的 顺序 排列 ， 同 样 可 以 
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弄 清楚 第 三 方 过 小 模块 为 何 要 在 ngx http headers filter module 模 块 之 后 、 
ngx_ http_userid filter module 模 块 之 前 。 





在 开发 HTTP 过 滤 模 块 时 ， ee 顺序 不 满意 ， 那 么 在 修改 
ngx_modules.c 文 件 时 先 要 对 照 表 6-1 看 一 下 每 个 模块 的 功能 是 人 否 符合 它 的 位 置 。 
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6.3 HTITP 过 涛 模块 的 开发 步 又 


HTTP 过 滤 模 块 的 开发 步骤 与 第 3 章 中 所 述 的 普通 HITP 模 块 的 开发 步骤 基本 一 致 ， 
再 简要 地 概括 一 下 ， 即 如 下 8 个 步 又 : 


1) 确定 源 代码 文件 名 称 。 通 常 ，HTTP 过 滤 模 块 的 功能 都 比较 单一 ， 因 此 ， 一 般 1 个 C 源 
文件 就 可 以 实现 1 个 HTTP 过 滤 模 块 。 由 于 需要 将 源 文件 加 入 到 Makefile 中 ， 因 此 这 时 就 要 确 
定好 源 文件 名 称 。 当 然 ， 用 多 个 C 源 文件 甚至 C++ 源 文 件 实现 1 个 HTTP 过 滤 模 块 也 是 可 以 
的 ， 可 参考 3.3 节 和 3.9 节 ， 这 里 不 再 歼 述 


2) 在 源 代 码 所 在 目录 创建 config 脚 本 文件 ， 当 执行 configure 时 将 该 目录 添加 进去 。config 
文件 的 编写 方法 与 3.3.1 中 开发 普 通 HITTP 模 块 时 介绍 的 编写 方法 基本 一 致 ， 唯 一 需要 改变 
的 是 ， 把 HITP MODULES 变 量 改 为 HITP_ FILTER _ MODULES 变 量 ， 这 样 才 会 把 我 们 的 模块 
作为 HTTP 过 滤 模 块 ， 并 把 它 放 置 到 正确 的 位 置 ( 图 6-1 所 示 的 第 三 方 过 滤 模 块 位 置 ) 上 。 











在 执行 configure 命 令 时 ， 其 编译 方法 与 3.3.2 节 中 介绍 的 是 一 样 的 。 在 执行 configure--add- 
module=PATH 时 ，PATH 就 是 HTTP 过 滤 模 块 源 文件 所 在 的 路 符 。 当 多 个 源 代 人 码 文件 实现 1 个 
HTTP 过 滤 模 块 时 ， 需 在 NGX ADDON SRCS 变 量 中 添加 其 他 源 代码 文件 。 





3) 定义 过 小 模块 。 实 例 化 ngx_module t 类 型 的 模块 结构 ， 这 与 3.4 节 介绍 的 内 容 类 似 ， 
同时 可 以 参考 3.5 节 中 的 例子 。 因 为 HITP 过 滤 模 块 也 是 HTTP 模块 ， 所 以 在 定义 ngx module t 
结构 时 ， 其 中 的 type 成 员 也 是 NGX _ HTTP MODULE。 这 一 步骤 与 定义 普通 的 HTTP 模块 是 相 
同 的 。 


4) 处 理 感 兴趣 的 配置 项 。 依 照 第 4 章 中 介绍 的 方法 ， 可 通过 设置 nex module tt 结构 中 的 
ngx_command t 数 组 来 处 理 感 兴趣 的 配置 项 。 





5) 实现 初始 化 方法 。 初 始 化 方法 就 是 把 本 模块 中 处 理 HTTP 头 部 的 
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ngx http output header filter pt 方法 与 处 理 HTTP 包 体 的 ngx http output body filter pt 方法 插入 
到 过 滤 模 块 链 表 的 首部 ， 参 见 6.2.1 节 中 的 例子 。 





6) 实现 处 理 HITTP 头 部 的 方法 。 实 现 ngx http_output header filter pt 原型 的 方法 ， 用 于 处 
理 HTTP 头 部 ， 如 下 所 示 : 





typedef ngx int t (*ngx http output header filter pt) (ngx http request t *r); 








一 定 要 在 模块 初始 化 方法 中 将 其 添加 到 过 小 模块 链表 中 。 


7) 实现 处 理 HTTP 包 体 的 方法 。 实 现 ngx http output body filter pt 原型 的 方法 ， 用 于 处 
理 HTTP 包 体 ， 如 下 所 示 : 





typedef ngx int t (*ngx http output body filter pt) (ngx http request t r, ngx chain t chain); 








一 定 要 在 模块 初始 化 方法 中 将 其 添加 a 到 过 小 模块 链表 中 。 


8) 编译 安装 后 ， 修 改 nginx.conf 文 件 并 局 动 目 定义 过 滤 模 块 。 通 常 ， 出 于 灵活 性 考虑 ， 
在 配置 文件 中 都 会 有 配置 项 决定 是 否 局 动 模块 。 因 此 ， 执 行 make 编 详 以 及 make install 安 装 
后 ， 再 修改 nginx.conf 文 件 中 的 配置 项 ， 目 定义 过 滤 模 块 的 功能 
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6.4 HTTP 过 滤 模 块 的 简单 例子 


本 节 通 过 一 个 简单 的 例子 来 说 明 如 何 开 发 HTTP 过 滤 模 块 。 场 景 是 这 样 的 ， 用 户 的 请 求 
由 static 静 态 文 件 模 块 进行 了 处 理 ， 它 会 根据 URI 返 回 磁盘 中 的 文件 给 用 户 。 而 我 们 开发 的 过 
小 模块 就 会 在 返回 给 用 户 的 啊 应 包 体 前 加 一 段子 符 串 :"[my filter prefixl]"。 需 要 实现 的 功能 
就 是 这 么 简单 ， 当 然 ， 可 以 在 配置 文件 中 决定 是 否 开 局 此 功能 。 








图 6-2 简 单 地 描绘 了 处 理 HTTP 头 部 的 方法 将 会 执行 的 操作 ， 而 图 6-3 则 是 处 理 HTTP 包 体 
的 方法 将 会 执行 的 操作 。 


TiNNinNnn http://wWwWw linuxorobe.con 
















盒 查 Content -Type 是 否 是 文本 类 型 


[ 包 体 的 类 型 是 文本 文件 ] 


设置 HTTP 上 下 文 表示 当前 请 求 的 响应 包 体 时 
要 加 前 组 






执行 下 一 个 过 滤 模 块 的 HTTP 


© 


图 6-2 过滤 模 块 例子 中 ，HTTP 头 部 处 理 方法 的 执行 活动 图 


[返回 非 200] 
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与 图 6-2 相 关 的 代码 可 参见 6.4.5 节 。 


检查 HTTP 上 下 文中 是 否 表 示 要 加 前 级 






[ 上 下 文中 显示 需要 处 理 的 包 体 ] Ne 
[不 需要 处 理 包 体 ] 


在 当前 待 发 送 的 HTIP 包 体 前 添加 前 级 


一 个 过 滤 模 块 的 HTTP 包 体 过 滤 方 法 


图 6-3” ”过滤 模块 例子 中 ，HTTP 包 体 处 理 方法 的 执行 活动 图 
与 图 6-3 相 关 的 代码 可 参见 6.4.6 节 。 


由 于 HTTP 过 滤 模 块 也 是 一 种 HTTP 模 块 ， 所 以 大 家 会 太 现 本 章 myfilter 过 滤 模 块 的 代码 与 
第 3 章 介 绍 的 例子 中 的 代码 很 相似 。 


6.4.1 ”如 何 编写 config 文 件 


口 由 掉 岂 有 所 和 所 掉 由 http' /wNv inuxorobe. con 





可 以 仅 用 1 个 源 文 件 实现 上 述 HTTP 过 滤 模 块 ， 源 文件 名 为 ngx_http myfilter module.c。 在 
该 文件 所 在 目录 中 添加 config 文 件 ， 其 内 容 如 下 : 





ngx addon name=ngx http myfilter module HTTP FILTER MODULES="$HTTP FILTER MODULES ngx http myfilter module" 




















NGX ADDON SRCS="$NGX ADDON SRCS S$ngx addon dir/ngx http myfilter module.c" 





将 模块 名 添加 到 HTTP_FILTER_MODULES 变 量 后 ，auto/modules 脚 本 就 会 按照 6.2.2 贡 中 
定义 的 顺序 那样 ， 将 ngx http myfilter module 过 滤 模 块 添 加 到 ngx modules 数 组 的 合适 位 置 
其 中 ，NGX ADDON SRCS 定 义 的 是 待 编 译 的 C 源 文件 。 


6.4.2 ”配置 项 和 上 下 文 


首先 希望 在 nginx.conf 中 有 一 个 控制 当前 HTTP 过 滤 模 块 是 否 生效 的 配置 项 ， 它 的 参数 值 
为 on 或 者 off， 分 别 表示 开启 或 者 关闭 。 因 此 ， 按 照 第 4 章 介绍 的 用 法 ， 需 要 建立 
ngx_http_myfilter_conf t 结 构 体 来 存储 配置 项 ， 其 中 使 用 ngx_flag t 类 型 的 enable 变 量 来 存储 这 
个 参数 值 ， 如 下 所 示 : 








typedef struct { 


ngx flag t enable; 


} ngx http myfilter conf t; 








同样 ， 下 面 实现 的 ngx http myfilter_ create_conf 用 于 分 配 存 储 配置 项 的 结构 体 
ngx_http_ myfilter conf t: 





static voidqx ngx http myfilter _ create conf (ngx conf 七 xcf) { 


人 站 全 conf_t 而 硬是 中 站 ptt D 1/ ww nuxprobe 





// 创建 存储 配置 项 的 结构 体 


mycf = (ngx http myfilter conf 七 *)ngx pcalloc(cf->pool, sizeof (ngx http myfilter conf t)); if (mycf == NU] 


return NULL; 


// ngx flat 七 类 型 的 变量 。 如 果 使 用 预 设 函 数 


ngx _ conf set flag slot 解 析 配 置 项 参数 ， 那么 必须 初始 化 为 





NGX CONF UNSET 





mycf->enable= NGX CONF UNSET; 





return mycf; 





就 像 gzip 等 其 他 HTTP 过 滤 模 块 的 配置 项 一 样 ， 我 们 往往 会 允许 配置 项 不 只 出 现在 
location{...} 配 置 块 中 ， 还 可 以 出 现在 server{...} 或 者 http{...} 配 置 块 中 ， 因 此 ， 还 需要 实现 一 
个 配置 项 值 的 合并 方法 一 一 ngx http myfilter merge conf， 代 人 码 如 下 所 示 : 











static Ghar * 
ngx http myfilter merge conf (ngx conf t cf, void parent, void *child) { 


ngx http myfilter conf t *prev = (ngx http myfilter conf t *)parent; ngx http myfilter conf t *conf = (ngx http 
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ngx_flat 七 类 型 的 配置 项 


enable 





ngx conf merge value (conf->enable, prev->enable, 0); return NGX CONF OR; 





根据 6.4.3 节 中 介绍 的 配置 项 名 称 可 知 ， 在 nginx.conf 配 置 文件 中 需要 有 “add_prefix on;” 字 
样 的 配置 项 。 





再 建立 一 个 HTTP 上 下 文 结构 体 ngx http myfilter ctx t， 其 中 包括 add_prefix 整 型 成 员 ， 在 
处 理 HITP 头 部 时 用 这 个 add_prefix 表 示 在 处 理 HTTP 包 体 时 是 否 添加 前 绥 。 





typedef struct { 


ngx int 七 add prefix; 


} ngx http myfilter ctx t; 





当 add_prefix 为 0 时 ， 表 示 不 需要 在 返回 的 包 体 前 加 前 级 ; 当 add_prefix 为 1 时 ， 表 示 应 当 
在 包 体 前 加 前 缀 ; 当 add_prefix 为 ?2 时， 表示 已 经 添加 过 前 级 了 。 为 什么 add_prefftx 有 3 个 值 
呢 ? 因为 HITP 头 部 处 理 方法 在 1 个 请 求 中 只 会 被 调用 1 次 ， 但 包 体 处 理 方法 在 1 个 请 求 中 是 有 
可 能 被 多 次 调用 的 ， 而 实际 上 我 们 只 希望 在 包头 加 1 次 前 级 ， 因 此 add_prefix 制 定 了 3 个 值 。 





6.4.3 ”定义 HTTP 过 滤 模 块 


定义 ngx module 模块 前 ， 需 要 先 定义 好 它 的 两 个 关键 成 员 ，ngx_command t 类 型 的 
commands 数 组 和 ngx http module t 类 型 的 ctx 成 员 。 
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下 面 定 义 了 ngx http_ myfilter commands 数 组 ， 它 会 处 理 add_prefix 配 置 项 ， 将 配置 项 参数 
解析 到 ngx_ http myfilter conf t 上 下 文 结构 体 的 enable 成 员 中 。 





static ngx command t ngx http myfilter commandqs [] = { 


{ ngx string("add prefix"), 


NGX HTTP MAIN CONF|NGX HTTP SRV CONF|NGX HTTP LOC CONF|NGX HTTP LMT CONF|NGX CONF FLAG, ngx co! 





NGX HTTP LOC CONF OFFSET, offsetof (ngx http myfilter conf t, enable), NULL }, 





ngx null command 





在 定义 ngx http module {类 型 的 ngx http myfilter module ctx 时 ， 需 要 将 6.4.2 节 中 定义 的 
ngx_http_myfilter_create_conf 回 调 方法 放 到 create_loc_conf 成 员 中 ， 而 
ngx_http_myfilter_merge_conf 回 调 方 法 则 要 放 到 merge_loc_conf 成 员 中 。 男 外 ， 在 6.4.4 节 中 害 
义 的 ngx_http_myfilter_init 模 块 初始 化 方法 也 要 放 到 postconfiguration 成 员 中 ， 表 示 当 读 取 完 所 
有 的 配置 项 后 就 会 回调 ngx http myfilter init 方 法 ， 代 码 如 下 所 示 : 








static ngx http module t ngx http myfilter module ctx = { 





NULL, /* preconfiguration 方 法 
*y 

ngx http myfilter init, /* postconfiguration 方 法 
2 

NULL, /* create main conf 方 法 
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NULL, 


NULL, 


NULL, 


/* init main conf 方 法 


4 


/* create srv conf 方 法 


yy 


/* merge srv conf 方 法 


4 


ngx http myfilter create conf,/* create loc conf 方 法 


ngx http myfilter merge conf 


发/ 


/* merge loc conf 方 法 
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有 了 ngx_command t 类 型 的 commands 数 组 和 ngx http module t 类 型 的 ctx 成 员 后 ， 下 面 就 可 
以 定义 ngx_http myfilter module 过 滤 模 块 了 。 





ngx module 


t ngx http myfilter module 





NGX MODULE V1, 


&ngx ht 


ngx_ htt 


NGX_HTT 


NULL, 











P_ MODULE 


tp myfilter module ctx, 


p_myfilter commands, 


Ap 


= 


/* module context */ 


/* module directives */ 


/* module type */ 


/* init master */ 


Ft: /Ww | 1 NUXor obe. con 





NULL, /* init process */ 


NULL, /* init thread */ 
NULL, /* exit thread */ 
NULL, /* exit process */ 
NULL, /* exit master */ 





NGX MODULE V1 PADDING 





它 的 类 型 仍然 是 NGX HTTP MODULE。 


6.4.4 初始 化 HITP 过 滤 模 块 





在 定义 ngx_http myfilter init 方 法 时 ， 首 先 需 要 定义 静态 指针 ngx_ http_ next header filter， 
用 于 指向 下 一 个 过 滤 模 块 的 HTTP 头 部 处 理 方法 ， 然 后 要 定义 静态 指针 
ngx_http_next_body_filter， 用 于 指 同 下 一 个 过 小 模块 的 HTTP 包 体 处 理 方法 ， 代 码 如 下 所 示 。 








static ngx http output header filter pt ngx http next header filter; static ngx http output body filter pt nN 








// 插入 到 头 部 处 理 方 法 链表 的 首部 


ngx http next header filter = ngx http top header filter; ngx http top header filter = ngx http myfilter he: 

















ngx http next body filter = ngx http top body filter; ngx http top body filter = ngx http myfilter body filli 
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6.4.5 处理 请 求 中 的 HITP 头 部 


我 们 需要 把 在 HTTP 啊 应 包 体 前 加 的 字符 串 前 级 便 编 码 为 filter_prefix 变 量 ， 如 下 所 示 。 





static ngx str t filter prefix = ngx string("[my filter prefix]"); 





根据 图 6-2 中 描述 的 处 理 流程 ，ngx http myfilter header filter 回 调 方法 的 实现 应 如 下 所 





static ngx int t 


ngx http myfilter header filter(ngx http request 七 *r) { 





ngx http myfilter ctx t he. 


ngx http myfilter conf 七 *conf; 


/* 如 果 不 是 返回 成 功 ， 那 么 这 时 是 不 需要 理 级 的 ， 直 接 交 由 下 一 个 过 滤 模 块 处 理 响 应 码 非 
200 的 情况 
4 
if (r->headers out.status != NGX HTTP OK) { 


return ngx http next header filter(r); } 








// 获取 


HLTP 
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ctx = ngx http get module ctx(r, ngx http myfilter module); if (ctx) { 





/* 该 请 求 的 上 下 文 已 经 存在 ， 这 说 明 





ngx http myfilter header filter 已 经 被 调用 过 


1 次 ， 直 接 交 由 下 一 个 过 滤 模 块 处 理 


4 





return ngx http next header filter(r); } 





// 获取 存储 配置 项 的 


ngx http myfilter conf 鞋 结构 体 


conf = ngx http get module loc conf(r, ngx http myfilter module); /* 如 果 





enable 成 员 为 


0， 也 就 是 配置 文件 中 没有 配置 


adqd prefix 配 置 项 ， 或 者 
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aqdq prefix 配 置 项 的 参数 值 是 


off， 那 么 这 时 直接 交 由 下 一 个 过 滤 模 块 处 理 


2 


if (conf->enable == 0) { 


return ngx http next header filter(r); } 








// 构造 


HTTP 上 下 文 结 构 体 


ngx http myfilter ctx t 


ctx = ngx pcalloc(r->pool, sizeof (ngx http myfilter ctx t)); if (ctx == NULL) { 





return NGX ERROR; 


// adqd prefix 为 


0 表示 不 加 前 组 


ctx->add prefix = 0; 


// 将 构造 的 上 下 文 设置 到 当前 请 求 中 
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ngx http set ctx(r, ctx, ngx http myfilter module); // myfilter 过 滤 模 块 只 处 理 


« 


Content-Type 是 


text/plain” 类 型 的 





HTTP 响 应 

if (r->headers out.content type.len >= Sizeof ("text/plain") - 1 

&& ngx strncasecmp (r->headers out.content type.data, (u char *) "text/plain",sizeof ("text/plain") - 1) == 0) { 
// 设置 为 

1 表示 需要 在 


HTTP 包 体 前 加 入 前 级 


ctx->add prefix = 1; 


/* 当 处 理 模 块 已 经 在 


cont 牛 二 直下 和 引证 站 由 有 由 由 由 Pttp:/AwNwv 1 nNuxporobe. con 





HTTP 包 体 的 长 度 时 ， 由 于 我 们 加 入 了 前 组 字符 串 ， 所 以 需要 把 这 个 字符 串 的 长 度 也 加 入 到 


Content-Length 中 
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if (r->headers out.content length n > 0) r->headers out.content length n += filter prefix.len; } 





// 交 由 下 一 个 过 滤 模 块 继续 处 理 





return ngx http next header filter(r); } 











注意 ， 除 非 出 现 了 严重 的 错误 ， 一 般 情况 下 都 需要 交 由 下 一 个 过 滤 模 块 继续 处 理 。 究 竟 
是 在 ngx_http_ myfilter_ header filter 函 数 中 直接 返回 NGX_ERROR， 还 是 调用 
ngx_http_next_header _ filter() 继 续 处 理 ， 读 者 可 以 参考 6.2.3 节 中 介绍 的 一 些 必需 的 过 滤 模 块 具 
备 的 功能 来 决定 。 


6.4.6 ”处 理 请 求 中 的 HTTP 包 体 


根据 图 6-3 中 描述 的 处 理 流程 看 ，ngx http myfilter body filter 回 调 方法 的 实现 应 如 下 所 





static ngx int t ngx http myfilter body filter (ngx http request t *r, ngx chain 七 *in) { 





ngx http myfilter ctx t eA. 


ctx = ngx http get module ctx(r, ngx http myfilter module); /* 如 果 获 取 不 到 上 下 文 ， 或 者 上 下 文 结构 体 中 的 
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adqd prefix 为 


2 时 ， 都 不 会 添加 前 级 ， 这 时 直接 交 给 下 一 个 


HTTP 过 滤 模 块 处 理 


2 


if (ctx == NULL || ctx->add prefix != 1) { 


return ngx http next body filter(r, in); } 





adq prefix 设 置 为 


2， 这 样 即使 


ngx http myfilter body filter 再 次 回调 时 ， 也 不 会 重复 添加 前 级 
*/ 


ctx->add prefix = 2; 


2 烛 相 人 国 全 下 和 人 再 全 下 站 http://wwwTinuxorobe. con 





ngx buf tx b = ngx create temp buf (r->pool, filter prefix.len); // 将 


ngx_buf 七 中 的 指针 正确 地 指向 


filter Prefix 字 符 串 


b->start = b->pos = filter prefix.data; b->last = b->pos + filter prefix.len; /x* 从 请 求 的 内 存 池 中 生成 


ngx_chain 七 链表 ， 将 刚 分 配 的 


ngx buf 七 设置 到 


buf 成 员 中 ， 并 将 它 添加 到 原先 待 发 送 的 


HTTP 包 体 前 面 

0 
ngx chain 七 xcl = ngx alloc chain link(r->pool); cl->buf = b; 
cl->next = in; 


// 调用 下 一 个 模块 的 
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HTTP 包 体 处 理 方法 ， 注 意 ， 这 时 传 入 的 是 新 生成 的 


Cl 链表 


return ngx http next body filterl(r, cl1); 








到 此 ， 一 个 简单 的 HTTP 过 滤 模 块 就 开 友 完成 了 。 无 论 功 能 多 么 复杂 的 HTTP 过 滤 模 块 ， 
一 样 可 以 从 这 个 例子 中 衍生 出 来 。 
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6.5 ”小结 





过 本 章 的 学 习 ， 读 者 应 该 已 经 掌握 如 何 编写 HTTP 过 滤 模 块 了 。 相 比 普通 的 HITP 处 理 
模块 ， 编 写 HTTP 过 小 模块 要 简单 许多 ， 因 为 它 不 可 能 去 访问 第 三 方 服务 ， 也 不 负责 发 送 啊 
应 到 客户 羔 。HTTP 过 小 模块 的 优势 在 于 厨 加 ， 即 1 个 请 求 可 以 被 许多 HTTP 过 滤 模 块 处 理 ， 
这 种 设计 带 来 了 很 大 的 灵活 性 。 读 者 在 开发 HTTP 过 滤 模 块 时 ， 也 要 把 模块 功能 分 解 得 更 单 
一 一 些 ， 即 在 功能 过 于 复杂 时 应 该 分 成 多 个 HTTP 过 滤 模 块 来 实现 。 
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第 7 音 Nginx 提 供 的 高 级 数据 结构 


任何 复杂 的 程序 都 需要 用 到 数组 、 链 表 、 树 等 数据 结构 ， 这 些 容 器 可 以 让 用 户 忽略 底层 
细节 ， 快 速 开 发 出 各 种 高 级 数据 结构 、 实 现 复杂 的 业务 功能 。 在 开发 Nginx 模 块 时 ， 同 样 也 
需要 这 样 的 高 级 通用 容器 。 然 而 ，Nginx 有 两 个 特点 : 路 平台 、 使 用 C 语 言 实现 ， 这 两 个 特点 
导致 Nginx 不 宜 使 用 一 些 第 三 方 中 间 件 提供 的 容器 和 算法 。 跨 平台 意味 着 Nginx 必 须 可 以 运行 
在 Windows、Linux 等 许多 主流 操作 系统 上 ， 因 此 ，Nginx 的 所 有 代码 都 必须 可 以 跨 平 台 编 
译 、 运 行 。 另 外 ，Nginx 是 由 C 语 言 开 发 的 。 虽 然 所 有 的 操作 系统 都 支持 C 语 言 ， 但 是 C 语 言 
与 每 一 个 操作 系统 都 是 强 相 关 的 ， 且 C 库 对 操作 系统 的 某 些 系统 调用 封装 的 方法 并 不 是 跨 平 
台 的 。 

















对 于 这 种 情况 ，Nginx 的 解决 方法 很 简单 ， 在 这 些 必须 特殊 化 处 理 的 地 方 ， 对 每 个 操作 
系统 孝 给 一 份 特 异化 的 实现 ， 因 此 ， 用 户 在 下 载 Nginx 源 码 包 时 会 发 现 有 Windows 版 本 和 
UNIX 版 本 。 而 对 于 基础 的 数据 结构 和 算法 ，Nginx 则 完全 从 头 实 现 了 一 壳 ， 如 动态 数组 、 链 
表 、 二 又 排序 树 、 散 列表 等 。 当 开发 功能 复杂 的 模块 时 ， 如 采 需 要 使 用 这 些 数 据 结构 ， 不 妨 
使 用 它们 来 加 快 开发 速度 ， 这 些 数据 结构 的 好 处 是 完全 使 用 C 语 言 从 头 实现 ， 运 行 效率 非常 
高 ， 而 且 和 它们 是 可 以 路 平台 使 用 的 ， 在 主流 操作 系统 上 都 可 以 正常 的 工作 。 





当然 ， 由 于 这 些 基 础 数据 结构 的 路 平台 特性 、C 语 言 面 问 过 程 的 特点 、 不 统一 的 使 用 风 
格 以 及 几乎 没有 注释 的 Nginx 源 代码 ， 造 成 了 它们 并 不 容易 使 用 ， 本 半 将 会 详细 阐述 它们 的 
设计 目的 、 思 想 、 使 用 方法 ， 并 通过 例子 形象 地 展示 这 些 容 器 的 使 用 方式 。 
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7.1 Nginx 提 供 的 高 级 数据 结构 概述 





本 章 将 介绍 Nginx 实 现 的 6 个 基本 容器 ， 熟 练 使 用 这 6 个 基本 容器 ， 将 会 大 大 提高 开发 
Nginx 模 块 的 效率 ， 也 可 以 更 加 方便 地 实现 复杂 的 功能 。 





ngx_queue { 双 回 链 表 是 Nginx 提 供 的 轻 量 级 链表 容 毁 ， 它 与 Nginx 的 内 存 池 无 天， 因此 ， 
这 个 链表 将 不 会 负责 分 配 内 存 来 存放 链表 元 素 。 这 意味 着 ， 任 何 链表 元 素 都 需要 通过 其 他 方 
式 来 分 配 它 所 需要 的 内 存 空间 ， 不 要 指望 ngx_queue_t 帮 助 存 储 元 素 。ngx_queue t 只 是 把 这 些 
己 经 分 配 好 内 存 的 元 素 用 双向 链表 连接 起 来 。ngx_queue tt 的 功能 虽然 很 简单 ， 但 它 非 常 轻 量 
级 ， 对 每 个 用 户 数据 而 言 ， 只 需要 增加 两 个 指针 的 空间 即 可 ， 消 耗 的 内 存 很 少 。 同 时 ， 
ngx_queue _t 还 提供 了 一 个 非常 简易 的 插入 排序 法 ， 虽 然 不 太 适 合 超大 规模 数据 的 排序 ， 但 它 
胜 在 简单 实用 。ngx_queue_t 作 为 C 语 言 提 供 的 通用 双 同 链表 ， 其 设计 思路 值得 用 户 参 考 。 














ngx_array_t 动 态 数组 类 似 于 C++ 语言 STL 库 的 vector 容 器 ， 它 用 连续 的 内 存 存放 着 大 小 相 
同 的 元 素 〈 就 像 数 组 ) ， 这 使 得 它 按照 下 标 检索 数据 的 效率 非常 高 ， 可 以 用 O(D) 的 时 间 来 访 
问 随机 元 素 。 相 比 数组 ， 它 的 优势 在 于 ， 数 组 通常 是 固定 大 小 的 ， 而 ngx array t 可 以 在 达到 
容量 最 大 值 时 自动 扩容 (扩容 算法 与 常见 的 vector 容 器 不 同 ) 。ngx array t 与 ngx queue t 的 一 




















个 显著 不 同 点 在 于 ，ngx queue t 并 不 负责 为 容器 元 素 分 配 内 存 ， 而 ngx array t 是 负责 容器 元 
素 的 内 存 分 配 的 。ngx array t 也 是 Nginx 中 应 用 非常 广泛 的 数据 结构 ， 本 章 介 绍 的 支持 通配符 
的 散 列 表 中 就 有 使 用 它 的 例子 。 














ngx_list_t 单 向 链表 与 ngx_queue_t 双 向 链表 是 完全 不 同 的 ， 它 是 负责 容器 内 元 素 内 存 分 配 
的 ， 因 此 ， 这 两 个 容器 在 通用 性 的 设计 思路 上 是 完全 不 同 的 。 同 时 它 与 ngx_array t 也 不 一 
样 ， 它 不 是 用 完全 连续 的 内 存 来 存储 元 素 ， 而 是 用 单 链表 将 多 段 内 存 块 连接 起 来 ， 每 段 内 存 
块 也 存储 了 多 个 元 素 ， 有 点 像 “ 数 组 + 单 链表 ”。 在 3.2.3 节 中 已 经 详细 介绍 过 ngx list t 单 向 链 
表 ， 本 章 不 再 鳌 述 。 
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ngx_rbtree t《〈 红 黑 树 ) 是 一 种 非常 有 效 的 高 级 数据 结构 ， 它 在 许多 系统 中 都 作为 核心 数 
所 结构 存在 。 它 在 检索 特定 关键 字 时 不 再 需要 像 以 上 容 吉 那样 过 有 历 容 锅 ， 同 时 ，ngx_rbtree { 
容器 在 检索 、 插 入 、 删 除 元 系 方 面 非常 高 效 ， 且 其 针对 各 种 类 型 的 数据 的 平均 时 间 都 很 优 
异 。 与 散 列 表 相 比 ，ngx_rbtree_t 还 文 持 范围 查询 ， 也 文 持 高 效 地 遇 历 所 有 元 素 ， 因 此 ， 
Nginx 的 核心 模块 是 离 不 开 ngx_rbtree 容器 的 。 同 时 ， 一 些 较 复 末 的 Nginx 模 块 也 都 用 到 了 
ngx_rbtree_t 容 如 。 用 户 在 需要 用 到 快速 检索 的 容器 时 ， 应 该 首先 考虑 是 不 是 使 用 


ngx rbtree t。 











ngx_radix tree {基数 树 与 ngx_rbtree t 红 黑 树 一 样 都 是 二 又 查找 树 ，ngx_rbtree {t 红 黑 树 具 
备 的 优点 ，ngx_radix _tree _t 基 数 树 同样 也 有 ， 但 ngx radix tree _t 基 数 树 的 应 用 范围 要 比 
ngx_rbtree _{t 红 黑 树 小 ， 因 为 ngx_radix_tree_t 要 求 元 素 必 须 以 整 型 数据 作为 关键 字 ， 所 以 大 大 
减少 了 它 的 应 用 场景 。 然 而 ， 由 于 ngx_radix tree t 基 数 树 在 插入 、 删 除 元 素 时 不 需要 做 旋转 
操作 ， 因 此 它 的 插入 、 删 除 效率 一 般 要 比 ngx rbtree t 红 黑 树 高 。 选 择 使 用 哪 种 二 又 查找 树 取 
决 于 实际 的 应 用 场景 。 不 过 ，ngx radix tree {基数 树 的 用 法 要 比 ngx_rbtree t 红 黑 树 简单 许 
多 。 











文 持 通配符 的 散 列 表 是 Nginx 独 创 的 。Nginx 首 先 实现 了 基础 的 常用 散 列 表 ， 在 这 个 基础 
上 ， 它 又 根据 Web 服 务 器 的 特点 ， 对 于 URI 域 名 这 种 场景 设计 了 文 持 通配符 的 散 列 表 ， 当 
然 ， 只 支持 前 置 通配符 和 后 置 通配符 ， 如 www.test.* 和 和 *.test.com。Nginx 对 于 这 种 散 列 表 做 了 
非常 多 的 优化 设计 ， 它 的 实现 较为 复杂 。 在 7.7 节 中 ， 将 会 非常 详细 地 描述 它 的 实现 ， 当 
然 ， 如 果 只 是 使 用 这 种 散 列表 ， 并 不 需要 完全 看 懂 7.7 节 ， 可 以 只 看 一 下 7.7.3 节 的 例子 ， 这 
将 会 简单 许多 。 不 过 ， 要 想 能 够 灵活 地 修改 Nginx 的 各 种 使 用 散 列 表 的 代码 ， 还 是 建议 读者 
仔细 阅读 一 下 7.7 节 的 内 容 。 
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7.2 ”nex queue {t 双 回 链 表 





ngx_queue_t 是 Nginx 提 供 的 一 个 基础 顺序 容器 ， 它 以 双 问 链表 的 方式 将 数据 组 织 在 一 
起 。 在 Nginx 中 ，ngx queue tt 数据 结构 被 大 量 使 用 ， 下 面 将 详细 介绍 它 的 特点 、 用 法 。 


7.2.1 为 什么 设计 ngx queue t 双 问 链 表 


链表 作为 顺序 容器 的 优势 在 于 ， 它 可 以 高 效 地 执行 插入 、 删 除 、 合 并 等 操作 ， 在 移动 链 
表 中 的 元 素 时 只 需要 修改 指针 的 指向 ， 因 此 ， 它 很 适合 频繁 修改 容器 的 场合 。 在 Nginx 中 ， 
链表 是 必 不 可 少 的 ， 而 ngx_queue_t 双 同 链表 就 被 设计 用 于 达成 以 上 目的 。 





相对 于 Nginx 其 他 顺序 容器 ，ngx_queue tt 容器 的 优势 在 于 : 
" 实现 了 排序 功能 


` 它 非常 轻 量 级 ， 是 一 个 纯粹 的 双向 链表 。 它 不 负责 链表 元 素 所 占 内 存 的 分 配 ， 与 
Nginx 封 装 的 ngx_pool_t 内 存 池 完全 无 关 。 


“ 支持 两 个 链表 间 的 合并 。 


ngx_queue t 容 器 的 实现 只 用 了 一 个 数据 结构 ngx queue t， 它 仅 有 两 个 成 员 : prev、 
next， 如 下 所 示 : 





typedef struct ngx queue s ngx queue t; 
struct ngx queue s { 





ngx queue t prev; 
ngx queue t next; 


}; 





因此 ， 对 于 链表 中 的 每 个 元 素来 说， 空间 上 只 会 增加 两 个 指针 的 内 存 消 耗 。 


信和 人 py WA TT oe ee 














ngx_queue t 来 标识 的 ， 而 链表 中 的 每 个 元 素 同 样 使 用 ngx_queue tt 结构 来 标识 自己 ， 并 以 
ngx_queue t 结 构 维 持 其 与 相 邻 元 素 的 关系 。 下 面 开 始 介 绍 ngx_queue t 的 使 用 方法 。 





7.2.2” 双 问 链 表 的 使 用 方法 





Nginx 在 设计 这 个 双 癌 链表 时 ， 由 于 容器 与 元 素 共 用 了 ngx_queue tt 结构 体 ， 为 了 避免 
ngx_queue_t 结 构 体 成 员 的 意义 混乱 ，Nginx 封 疾 了 链表 容 占 与 元 素 的 所 有 方法 ， 这 种 情况 非 
第 少见 ， 而 且 从 接 下 来 的 几 节 中 可 以 看 到 ， 其 他 容器 都 需要 直接 使 用 成 员 变 量 来 访问 ， 唯 有 
ngx_queue_t 双 同 链表 只 能 使 用 图 7-1 中 列 出 的 方法 访问 容 莫 。 











mx HH 
ngx gueue t 容 售 


TPICV 
rnext 


queue init() 人 
本 [yw ie Ze! 所 了 1F 、 3 E23 
queue empty() ngx_queue_t 容 天 中 的 元 系 


queue insert head() 
queue Insert tail() Fnext 

queue head () tnex queue next () 

queue last () Hngx queue Prev () 






queue sentinel () tnex queue data () 


queue remove () Fngx queue insert atfter () 
queue _ split (0) 

queue add () 

queue middle () 

queue sort() 


图 7-1 ngx_queue_t 容 器 提供 的 操作 方法 





使 用 双向 链表 容器 时 ， 需 要 用 一 个 ngx_queue t 结 构 体 表示 容 嚣 本身 ， 而 这 个 结构 体 共有 
12 个 方法 可 供 使 用 ， 表 7-1 中 列 出 了 这 12 个 方法 的 意义 。 


表 7-1 ngx_queue_t 双 向 链表 容器 所 支持 的 方法 
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方法 名 参数 含义 执行 意义 

h 为 链表 容 融 结构 体 ngx_queue_ t| 将 链表 容 占 h 初始化， 这 时 会 月 动 置 为 空 
的 指针 链表 

检测 链表 容器 中 是 否 为 空 ， 即 是 否 没 有 一 
个 元 素 存在 。 如 果 返 回 非 0， 表 示 链 表 }h 是 
空 的 


ngx queue init(h) 


h 为 链表 容 天 结构 体 ngx_queue { 
的 指针 


ngx queue empty(h) 


h 为 链表 容 融 结构 体 ;1 ngx_queve 
ngx_ queue insert head(h, x) |t 的 指针 ,x 为 插入 元 素 结构 体 中 | 将 元 素 x 插 入 到 链表 容器 的 头 部 
ngx_queue t 成员 的 指针 
h 为 链表 容 带 结构 体 ngx_queue_ 
ngx_queue insert tail(h, x) |t 的 指针 , x 为 插入 元 素 结 构 体 中 | 将 元 素 x 添加 到 链表 容器 的 末尾 
ngx_queue t 成 员 的 指针 





h 为 链表 容器 结构 体 ngx_queue t| 返回 链表 容器 中 的 第 一 个 元 素 的 ngx_ 
eed queue + 结构 体 指针 

h 为 链表 容器 结构 体 ngx_queue t| 返回 链表 容 岩 中 的 最 后 一 个 无 素 的 ngx_ 
的 指针 queue t 结构 体 指针 

h 为 链表 容 带 结构 体 ngx_queue { 
的 指针 

x 为 插入 元 素 结 构 体 中 ngx_ 
queue t 成 员 的 指针 


ngx queue head(h) 


ngx queue last(h) 


ngx queue sentinel(h) 返回 链表 容 才 结构 体 的 指针 





ngx queue remove(x) 由 容 需 中 移 除 x 元素 





( 续 ) 


FR i 
ngx_queue_split 用 于 拆 分 链表 , h 是 链表 
容器 ， 而 q 是 链表 了 中 的 一 个 元 素 。 这 个 方 
h 为 链表 容器 结构 体 ngx_queue t | 法 将 链表 了 以 元 素 q 为 界 拆 分 成 两 个 链表 
的 指针 和 n， 其 中 了 由 原 链表 的 前 半 部 分 构成 (不 包 
括 q)， 而 n 由 原 链表 的 后 半 部 分 构成 ，q 是 
它 的 首 元 素 


ngx queue split(h, q. D) 


h 为 链表 容 融 结构 体 ngx_queue_ 
ngx queue add(h. n) t 的 指针 ，n 为 另 一 个 链表 容器 结构 | 合并 链表 ,将 1n 链表 添加 到 上 链表 的 末尾 
体 ngx_queue t 的 指针 
返回 链表 中 心 元 素 ， 如 ,链表 共有 N 个 元 
h 为 链表 容器 结构 体 ngx_queue t| 素 ,ngx queue middle 方 法 将 返回 第 N/2+1 
的 指针 个 元 素 。 例 如 ， 链 表 有 4 个 元 素 ， 将 会 返回 


第 3 个 元 素 (不 是 第 2 个 元 素 ) 


h 为 链表 容器 结构 体 ngx_queue_ | 使 用 插入 排序 法 对 名和 过 行 排序 ，cmpfunc 
t 的 指针 ，cmpfunc 是 两 个 链表 元 素 | 需 要 使 用 者 自己 实现 ， 它 的 原型 是 这 样 的 : 
的 比较 方法 ， 如 果 它 返回 正 数 ， 则 |ngx_int_t (*cmpfunc)(const ngx_queue_t *, 
表示 以 升序 排序 const ngx_queue t *) 
VWWV UI OC, U 


ngx queue middle(h) 


ngx queue sort(h,.cmpfunc) 








对 于 链表 中 的 每 一 个 元 素 ， 其 类 型 可 以 是 任意 的 struct 结 构 体 ， 但 这 个 结构 体 中 必须 要 有 
一 个 ngx_queue t 铁 型 的 成 员 ， 在 同 链 表 容 器 中 添加 、 删 除 元 素 时 都 是 使 用 的 结构 体 中 
ngx_queue_t 类 型 成 员 的 指针 。 当 ngx_queue_t 作 为 链表 的 元 又 成 员 使 用 时 ， 它 共有 表 7-2 中 列 出 
的 4 种 方法 。 


表 7-2 nex_queue_t 双 向 链表 中 的 元 素 所 支持 的 方法 


方法 名 执行 意义 


q 为 链表 中 某 一 个 元 素 结构 体 的 ngx_ 


ngx queue next(q) >、 各 让 忆 大 
queue t 成 员 的 指针 





q 为 链表 中 某 一 个 元 素 结构 体 的 ngx_ 

queue t 成 员 的 指针 
qd 为 链表 中 某 一 个 元 素 结 构 体 的 ngx_ 
queue t 成 员 的 指针 ，type 为 链表 元 素 的 结 
ngx_queue_data(q, type, link) ”| 构 体 类 型 名 称 (该 结构 体 中 必须 包含 ngx_ 
queue t 类 型 的 成 员 )，link 是 上 面 这 个 结构 


ngx_queue_prev(q) 返回 q 元 素 的 上 一 个 元 素 

返回 q 元 素 (ngx queue t 类 型 ) 
所 属 结构 体 (任何 struct 类 型 ， 其 
中 可 在 任意 位 置 包 售 ngx_queue_t 
类 型 的 成 员 ) 的 地 址 


体 中 ngx_queue t 类 型 的 成 员 名 字 


qd 为 链表 中 某 个 元 素 结 构 体 的 ngx_ 


ngx queue insert after(q. x) queue t 成 员 的 指针 ，x 为 插入 元 素 结构 体 | 将 元 素 x 插入 到 元 素 q 之 后 





中 ngx_queue t 成 员 的 指针 


在 表 7-1 和 表 7-2 中 ， 己 经 列 出 了 链表 支持 的 所 有 方法 ， 下 面 将 以 一 个 简单 的 例子 来 说 明 
如 何 使 用 ngx queue t 双 同 链 表 。 


7.2.3 ”使 用 双向 链表 排序 的 例子 








本 节 定 义 一 个 简单 的 链表 ， 并 使 用 ngx_queue_sort 方 法 对 所 有 元 素 排序 。 在 这 个 例子 中 ， 
可 以 看 到 如 何 定 义 、 初 始 化 ngx_queue t 和 容器， 如 何 定义 任意 类 型 的 链表 元 素 ， 如 何 训 历 链 
表 ， 如 何 目 定 义 排序 方法 并 执行 排序 。 


首先 ， 定 义 链表 元 系 的 结构 体 ， 如 下 面 的 TestNode 结 构 体 : 





typedef struct { 
u Char* str; 
ngx queue 


[由 平和 站 中 站 由 由 http' /ww inuxorobe. con 








} TestNode; 








链表 元 系 结 构 体 中 必须 包含 ngx_queue t 类 型 的 成 员 ， 当 然 它 可 以 在 任意 的 位 置 上 。 本 例 
中 它 的 上 面 有 一 个 char* 指 针 ， 下 面 有 一 个 整 型 成 员 num， 这 样 是 允许 的 。 








排序 方法 需要 上 自 定 义 。 下 面 以 TestNode 结 构 体 中 的 num 成 员 作 为 排序 依据 ， 实 现 
compTestNode 方 法 作为 排序 过 程 中 任意 两 元 素 间 的 比较 方法 。 








ngx int t compTestNode (const ngx queue tx a, const ngx queue t* b) 


/* 首 先 使 用 


ngx_queue data 方 法 由 


ngx_queue 变量 获取 元 素 结构 体 


TestNode 的 地 址 


/ 





TestNode aNode = ngx queue data(a TestNode, qEle); 
TestNode* pbNode = ngx queue datal(lb, TestNode, qEle); 
// 返回 








num 成 员 的 比较 结果 


return aNode->num > bNode->num; 





这 个 比较 方法 结合 ngx_queue_sort 方 法 可 以 把 链表 中 的 元 系 按 照 hum 的 大 小 以 升序 排列 。 
在 此 例 中 ， 可 以 看 到 ngx_ queue_ data 的 用 法 ， 即 可 以 根据 链表 元 系 结 构 体 TestNode 中 的 qEle 成 
员 地 址 换算 出 TestNode 结 构 体 变量 的 地 址 ， 这 是 面向 过 程 的 C 语 言 编写 的 ngx_queue 人 链表 之 
所 以 能 够 通用 化 的 关键 。 下 面 来 看 一 下 ngx_queue_data 的 定义 : 





#define ngx queue datal(q,type,link) \ 
(type ) ((u char ) q - offsetof (type, link)) 





在 4.2.2 节 中 曾经 提 到 过 offsetof 函 数 是 如 何 实 现 的 ， 即 它 会 返回 link 成 员 在 type 结 构 体 中 的 
偏 移 量 。 例 如 ， 在 上 例 中 ， 可 以 通过 ngx queue t 类 型 的 指针 减 去 qEle 相 对 于 TestNode 的 地 址 
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偏 移 量 ， 得 到 TestNode 结 构 体 的 地 址 。 





下 面 开 始 定义 双向 链表 容器 queueContainer， 并 将 其 初始 化 为 空 链表 ， 如 下 所 示 。 





ngx _ queue t queueContainer; 
ngx queue init(&queueContainer); 














链表 容器 以 ngx_queue t 定 义 即 可 。 注 意 ， 对 于 表示 链表 容器 的 ngx_queue t 结 构 体 ， 必 须 
调用 ngx queue init 进 行 初始 化 。 











ngx queue {t 双 回 链表 是 完全 不 负责 分 配 内 存 的 ， 每 一 个 链表 元 素 必 须 目 己 管理 自己 所 占 
用 的 内 存 。 因 此 ， 本 例 在 进程 栈 中 定义 了 5 个 TestNode 结 构 体 作为 链表 元 素 ， 并 把 它们 的 num 
成 员 初 始 化 为 0(、1、2、3、4， 如 下 所 示 。 





int i = 0; 
TestNode node[5]; 
下 (< 
{ 
node[i]j .num = 工 ; 


} 





下 面 把 这 S 个 TestNode 结 构 体 添 加 到 queueContainer 链 表 中 ， 注 意 ， 这 里 同时 使 用 了 
ngx _ queue insert tail、ngx queue insert head、ngx queue insert after 3 个 添加 方法 ， 读 者 不 妨 
思考 一 下 链表 中 元 素 的 顺序 是 什么 样 的 。 








ngx queue insert tail(&queueContainer, &node[0] .gqEle 
ngx queue insert head(&queueContainer, &node[1] .gqEle 
ngx queue insert tail(&queueContainer, &node[2].qI 
ngx queue insert after(&queueContainer, &node[3] .gqEle); 
ngx queue insert tail(&queueContainer, &node[4] .gqEle); 





); 
); 





























根据 表 7-1 中 介绍 的 方法 可 以 得 出 ， 如 果 此 时 的 链表 元 系 顺 序 以 mom 成员 标识 ， 那 么 应 该 
古 这 样 的 ，3、1、0、2、4。 如 末 有 疑问 ， 不 妨 写 个 人 吉 历 链表 的 程序 检验 一 下 顺 友 是 否 如 
此 。 下 面 束 根据 表 7-1 中 的 方法 说 明 编写 一 段 蚀 单 的 所 历 链 表 的 程序 。 














ngx queue t* q; 
for (qd = ngx queue head(&queueContainer) 


TT pT httpo: // ww |i nuxpr obe. con 








q = ngx queue next (9q)) 

{ 
TestNode* eleNode = ngx queue datal(lq, TestNode, qEle); 
// 处 理 当 前 的 链表 元 素 








eleNode 


上 面 这 段 程序 将 会 依次 从 链表 头 部 过 历 到 尾部 。 反 辐 过 历 也 很 简单 。 读 者 可 以 符 试 使 用 
ngx queue _last 和 nsx_ queue prev 方 法 编写 相关 代码 。 


下 面 开始 执行 排序 ， 代 码 如 下 所 示 。 


ngx queue sort(&queueContainer, compTestNode); 


这 样 ， 链 表 中 的 元 素 就 会 以 9、、1、2、3、4 num 成员 的 值 ) 的 升序 排列 了 。 





表 7-1 中 列 出 的 其 他 方法 就 不 在 这 里 一 一 举例 了 ， 使 用 方法 非常 相似 。 
7.2.4” 双 问 链 表 是 如 何 实现 的 


本 节 将 说 明 ngx queue t 链 表 容 器 以 及 元 素 中 prev 成 员 、next 成 员 的 意义 ， 整 个 链表 就 是 
通过 这 两 个 指针 成 员 实现 的 。 


下 面 先 来 看 一 下 ngx queue t 结 构 体 作为 容器 时 其 prev 成 员 、next 成 员 的 意义 。 当 容 右 为 
空 时 ，prev 和 next 都 将 指 问 容器 本 映 ， 如 图 7-2 所 示 。 


如 图 7-2 所 示 ， 如 果 在 某 个 结构 体 中 定义 了 ngx queue tt 容器， 其 prev 指 针 和 next 指 针 都 会 
指向 ngx queue t 城 员 的 地 址 。 
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ngx_dueue _t 


D3 HH .Fe 
容 融 是 空 的 


图 7-2” 空 容器 时 ngx_queue_t 结 构 体 成 员 的 值 


当 容 器 不 为 空 时 ，ngx_queue tt 容器 的 next 指 针 会 指 同 链表 的 第 1 个 元 素 ， 而 prev 指 针 会 指 
癌 链表 的 最 后 1 个 元 素 。 如 图 7-3 所 示 ， 这 时 链表 中 只 有 1 个 链表 元 素 ， 容 器 的 next 指 针 和 prev 
间 针 都 将 指 癌 这 个 唯一 的 链表 元 素 。 






nex_dqueue_i 


nex_dueue 1 


2 3 穴 弄 口 右 1 人 于 讲 
ngx_queue_t 容 诊 和 容 基 只 有 1 个 元 系 





图 7-3” 当 仅 含 1 个 元 素 时 ， 容 器 、 元 素 中 的 nex_queue t 结 构 体 成 员 的 值 


对 于 每 个 链表 元 际 来 说 ， 其 prev 成 员 都 指 癌 前 一 个 元 素 《〈 不 存在 时 指 癌 链表 容 右 ) ， 而 
next 成 员 则 指向 下 一 个 元 素 〔 不 存在 时 指 癌 链表 容 右 〉， 这 在 图 7-3 中 可 以 看 到 。 


当 容 器 中 有 两 个 元 素 时 ，prev 和 next 的 指向 如 图 7-4 所 示 。 
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已 Th 1 人 村 
pe dqueue_1 指 问 第 1 个 元 又 ngx_dueue _t 
A AN | = 


SEE _ 
AP Ey AP Hy 29 有 和 AP 也 有 PP A -< 下 = 
ngx_dueue 上 容 厦 容 需 中 的 第 1 个 元 素 容 需 中 的 第 2 个 元 素 


图 7-4 ” 当 含 有 两 个 或 多 个 元 素 时 ， 容 器 、 元 素 中 的 ngx_queue_t 结 构 体 中 prev、next 成 员 的 值 











图 7-4 很 好 地 诠释 了 前 面 的 定义 ， 容 器 中 的 prev 成 员 指 向 最 后 1 个 也 就 是 第 2 个 元 素 ，next 
成 员 指 癌 第 1 个 元 素 。 第 1 个 元 素 的 prev 成 员 指 同 容 器 本 喘 ， 而 其 next 成 员 指 癌 第 2 个 元 素 。 第 


2 个 元 素 的 prev 成 员 指 癌 第 1 个 元 系 ， 其 next 成 员 则 指 疝 容 器 本 里。 





ngx_queue_ 的 实现 就 是 这 么 简单 ， 但 它 的 排序 算法 ngx_queue_sort 使 用 的 插入 排序 ， 并 不 
适合 为 庞大 的 数据 排序 。 
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7.3 nsx array t 动 态 数组 


ngx_array_t 是 一 个 顺序 容器 ， 它 在 Nginx 中 大 量 使 用 。ngx array t 容 右 以 数组 的 形式 存储 
元 素 ， 并 支持 在 达到 数组 容量 的 上 限时 动态 改变 数组 的 大 小 。 


7.3.1 为 什么 设计 ngx_array 动态 数组 


数组 的 优势 是 它 的 访问 速度 。 由 于 它 使 用 一 块 完整 的 内 存 ， 并 按照 固定 大 小 存储 每 一 个 
元 素 ， 所 以 在 访问 数组 的 任意 一 个 元 素 时 ， 都 可 以 根据 下 标 直 接 寻 址 找到 它 ， 另 外 ， 数 组 的 
访问 速度 是 常量 级 的 ， 在 所 有 的 数据 结构 中 它 的 速度 都 是 最 快 的 。 然 而 ， 正 是 由 于 数组 使 用 
一 块 连续 的 内 存 存储 所 有 的 元 素 ， 所 以 它 的 大 小 直接 决定 了 所 消耗 的 内 存 。 可 见 ， 如 果 预 分 
配 的 数组 过 大 ， 肯 定 会 浪费 宝贵 的 内 存 资源 。 那 么 ， 数 组 的 大 小 完 竟 应 该 分 配 多 少 才 是 够 用 
的 呢 ? 当 数 组 大 小 无 法 确定 时 ， 动 态 数组 就 “登场 "了 。 




















C++ 语言 的 STL 中 的 vector 容 器 就 像 ngx_array {t 一 样 是 一 个 动态 数组 。 它 们 在 数组 的 大 小 
达到 已 经 分 配 内 存 的 上 限时 ， 会 自动 扩充 数组 的 大 小 。 有 具备 了 这 个 特点 之 后 ，ngx_array _t 动 
态 数 组 的 用 处 就 大 多 了 ， 而 且 它 内 置 了 Nginx 封 装 的 内 存 池 ， 因 此 ， 它 分 配 的 内 存 也 是 在 内 
存 池 中 申请 得 到 。ngx_array t 容 器 具备 以 下 3 个 优点 : 





-访问 速度 快 。 
-允许 元 素 个 数 具备 不 确定 性 。 


.负责 元 素 占 用 内 存 的 分 配 ， 这 些 内 存 将 由 内 存 池 统一 管理 。 


7.3.2 ”动态 数组 的 使 用 方法 
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ngx array {t 动 态 数 组 的 实现 仅 使 用 1 个 结构 体 ， 如 下 所 示 。 





typedef struct ngx array S ngx array t; 
struct ngx array s 1 


// elts 指 向 数组 的 首 地 址 





void *elts; 


// nelts 是 数组 中 已 经 使 用 的 元 素 个 数 


ngx uint t nelts; 


// 每 个 数组 元 素 占用 的 内 存 大 小 


size 七 size; 


// 当前 数组 中 能 够 容纳 元 素 个 数 的 总 大 小 


ngx uint t nalloc; 


// 内 存 池 对 象 


ngx Pool 七 *pool; 








在 上 面 这 段 代 码 中 已 经 简单 描述 了 ngx array t 结 构 体 中 各 成 员 的 意义 ， 通 过 图 7-5， 读 者 
可 以 有 更 直观 的 理解 。 
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蔡 分 配 了 nalloc 个 元 素 









已 经 存储 了 nelts 个 元 于 


-个 元 骏 所 占 字 节 (Size ) 






ngx array 1{ 


+elts 
elts 指 回 动态 数组 的 首 地 址 Fnelts 

+ S1Ze 
Fnalloc 
+ pool 









tngx array create () 
tngx array init () 
tngx array destroy () 
tngx array push () 
tngx array push n() 








图 7-5 ”ngx_array_t 动 态 数 组 结构 体 中 的 成 员 及 其 提供 的 方法 
从 图 7-5 中 可 以 看 出 ，ngx array 动态 数组 还 提供 了 5 个 基本 方法 ， 它 们 的 意义 见 表 7-3。 


表 7-3 negx_attay_t 动 态 数 组 提供 的 方法 
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方法 名 生意 


p 是 内 池 \ 
是 内 存 池 , n 是 初始 分 配 i A 
i 创建 1 个 动态 数组 ， 并 预 分 配 n 个 大 小 


ngx array_create(ngx pool t *p,. .个 数 
为 size 的 内 存 空间 


元 素 的 最 大 size 是 每 


ngx uint tn, size t size) 
i ` 元 素 所 占用 的 内 存 大 小 


a 是 一 个 动态 数组 结构 体 的 
ngx array init(ngx array t *a., 指针 , p 是 内 存 池 , n 是 初始 | 初始 化 1 个 已 经 存在 的 动态 数组 ， 并 预 
ngx pool t *p., ngx uint tn., size tsize) | 分 En 的 最 大 个 数 ，size 是 | 分 配 n 个 大 小 为 size 的 内 存 空间 
每 一 个 元 素 所 占用 的 内 存 大 小 


销毁 已 经 分 配 的 数组 元 素 空 间 和 nesgx_ 
-个 动态 数组 结构 体 的 array_t 动 态 数 组 对 象 。 注 意 : ngx_array_ 

ngx_array_destroy(ngx_array_t *a) destroy 最 好 与 ngx_array_create 配对 使 用 ， 
因为 ngx_array_destroy 同 时 会 回收 ngx_ 


atray_t 结构 体 自 身 占用 的 内 存 


机 并 时 半 

问 当 前 a 动态 数组 中 添加 1 个 元 素 ， 返 
回 的 是 这 个 新 添加 元 素 的 地 址 注意 : 如 
果 动 态 数组 已 经 达到 容量 上 限 ， 这 时 会 自 
动 扩容 ， 到 底 扩 容 多 少 字 节 , 在 7.3.4 节 中 
说 明 
ngx array push n(ngx array t *a. a 是 一 个 动态 数组 结构 体 的 指 | 问 当 前 a 动态 数组 中 添加 1 个 元 素 ， 返回 
ngx_ uint tn) 省 ，n 是 需要 添加 元 素 的 个 数 “| 的 是 新 添加 这 批 元 素 中 第 一 个 元 素 的 地 址 


方法 名 


ngx array push(ngx array_t *a) 





如 果 使 用 已 经 定义 过 的 ngx array t 结 构 体 ， 那 么 可 以 先 调 用 ngx array init 方 法 初始 化 动 
态 数 组 。 如 果 要 重新 在 内 存 池上 定义 ngx array it 结构 体 ， 则 可 以 调用 ngx array_create 方 法 创 
建 动态 数组 。 这 两 个 方法 都 会 预 分 配 一 定 容量 的 数组 元 素 。 


在 向 动态 数组 中 琴 加 新 元 素 时 ， 最 好 调用 ngx_array_push 或 者 ngx_array_push_n 方 法 ， 这 
两 个 方法 会 在 达到 数组 预 分 配 容量 上 限时 自动 扩容 ， 这 比 直 接 操作 ngx_array_t 结 构 体 中 的 成 
员 要 好 得 多 ， 具 体 将 在 7.3.3 节 的 例子 中 详细 说 明 。 





@ 注意 ”因为 ngx_array_desttroy 是 在 内 存 池 中 销毁 动态 数组 及 其 分 配 的 元 素 内 存 的 (如 
果 动 态 数组 的 ngx_attay_t 结 构 体 内 存 是 利用 栈 等 非 内 存 池 方式 分 配 ， 那 么 调用 
ngx_attay_desttoy 会 导致 不 可 预 估 的 错误 ) ， 所 以 它 必须 与 ngx_array_create 配 对 使 用 。 
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7.3.3 ”使 用 动态 数组 的 例子 


本 市 以 一 个 简单 的 例子 说 明 如 何 使 用 动态 数组 。 这 里 仍然 以 7.2.3 中 介绍 的 TestNode 作 为 
数组 中 的 元 素 类 型 。 首 先 ， 调 用 ngx array_create 方 法 创建 动态 数组 ， 代 人 码 如 下 。 





ngx array tx dynamicArray = ngx array create(cf->pool, 1, sizeof (TestNode)); 








这 里 创建 的 动态 数组 只 预 分 配 了 1 个 元 素 的 空间 ， 每 个 元 又 占用 的 内 存 字 节 数 为 
sizeof(TestNode)， 也 就 是 TestNode 结 构 体 占 用 的 空间 大 小 。 


然后 ， 调 用 ngx array push 方 法 向 dynamicArray 数 组 中 添加 两 个 元 素 ， 代 人 码 如 下 。 





TestNode* a = ngx array push (dynamicArray); 
a->num = 1; 

a = ngx array push (dynamicArray); 

a->num = 2; 








这 两 个 元 素 的 num 值 分 别 为 1 和 2。 注 意 ， 在 添加 第 2 个 元 兹 时 ， 实 际 已 经 发 生 过 一 次 扩容 
了 ， 因 为 调用 ngx array_create 方 法 时 只 预 分 配 了 1 个 元 素 的 空间 。 下 面 尝 试用 
ngx_array_push_n 方 法 一 次 性 添加 3 个 元 兹 ， 代 码 如 下 。 





TestNode* b = ngx array Push nl(dynamicArray, 3); 
b->num = 3; 

(b+1)->num = 4; 

(b+2) ->num = 5; 








这 3 个 元 素 的 num 值 分 别 为 3、4、5。 下 面 来 看 一 下 是 如 何 遍 历 dynamicArray 动 态 数 组 
的 ， 代 码 如 下 。 





TestNode* nodeArray = dynamicArray->elts; 
ngx uint t arraySeq = 0; 
for (; arraySeq < dynamicArray->nelts; arraySeqt++) 


{ 





a = nodeArray + arraySeq; 


// 下 面 处 理 数组 中 的 元 素 
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了 解 了 遍历 dynamicArray 动 态 数组 的 方法 后 ， 再 来 看 一 下 销毁 动态 数组 的 方法 ， 这 就 非 
常人 简单 了 ， 如 下 所 示 : 





ngx array destroy (dynamicArray); 





7.3.4 动态 数组 的 扩容 方式 








本 节 将 介绍 当 动 态 数组 达到 容量 上 限时 是 如 何 进行 扩容 的 。ngx_array_push 和 
ngx array_push n 方 法 都 可 能 引发 扩容 操作 。 


当 己 经 使 用 的 元 素 个 数 达到 动态 数组 预 分 配 元 素 的 个 数 时 ， 再 次 调用 ngx_array_ push 或 
者 ngx_array_push_n 方 法 将 引发 扩容 操作 。ngx_array_push 方 法 会 申请 ngx_array t 结 构 体 中 size 
字 节 大 小 的 内 存 ， 而 ngx_array_push_n 方 法 将 会 申请 n (n 是 ngx_array_push_n 的 参数 ， 表 示 需 
要 添加 n 个 元 素 〉 个 size 字 节 大 小 的 内 存 。 每 次 扩容 的 大 小 将 受制 于 内 存 池 的 以 下 两 种 情形 : 





" 如 果 当 前 内 存 池 中 剩余 的 空间 大 于 或 者 等 于 本 次 需要 新 增 的 空间 ， 那 么 本 次 扩容 将 只 
扩充 新 增 的 空间 。 例 如 ， 对 于 ngx_array_push 方 法 来 说 ， 就 是 扩充 1 个 元 素 ， 而 对 于 


ngx_array_push_n 方 法 来 说 ， 就 是 扩充 n 个 元 素 。 


如 果 当 前 内 存 池 中 剩余 的 空间 小 于 本 次 需要 新 增 的 空间 ， 那 么 对 ngx_array_push 方 法 来 
说 ， 会 将 原先 动态 数组 的 容量 扩容 一 倍 ， 而 对 于 ngx_atray_push_n 来 说 ， 情 况 更 复杂 一 些 ， 如 
果 参 数 n 小 于 原先 动态 数组 的 容量 ， 将 会 扩容 一 倍 ; 如果 参 数 n 大 于 原先 动态 数组 的 容量 ， 这 
时 会 分 配 2Xn 大 小 的 空间 ， 扩 容 会 超过 一 倍 。 这 体现 了 Nginx 预 估 用 户 行为 的 设计 思想 。 





在 以 上 两 种 情形 下 扩容 的 字 节 数 都 与 每 个 元 素 的 大 小 相关 。 


人 @@ 注意 工 述 第 ?种 情形 涉及 数据 的 复制 。 新 扩容 一 们 以 上 的 动态 数组 将 在 全 新 的 内 在 
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7.4 nsx list { 单 回 链 表 


ngx_list_t 也 是 一 个 顺序 容 费 ， 它 实际 上 相当 于 7.3 节 中 介绍 的 动态 数组 与 单 向 链表 的 结合 
体 ， 只 是 扩容 起 来 比 动态 数组 简单 得 多 ， 它 可 以 一 次 性 扩容 1 个 数组 。 在 图 3-2 中 描述 了 
ngx_list_t 容 器 中 各 成 员 的 意义 ， 而 且 在 3.2.3 节 中 详细 介绍 过 它 的 用 法 ， 这 里 不 再 歼 述 。 
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7.5 ”ngx rbtree t 红 黑 树 


ngx_rbtree_t 是 使 用 红 黑 树 实现 的 一 种 关联 容器 ，Nginx 的 核心 模块 (如 定时 器 管理 、 文 
件 缓存 模块 等 ) 在 需要 快速 检索 、 碍 找 的 场合 下 都 使 用 了 ngx rbtree t 和 容器， 本 节 将 系统 地 讨 
论 ngx_rbtree t 的 用 法 ， 并 以 一 个 贯穿 本 节 始 终 的 例子 对 它 进行 说 明 。 在 这 个 例子 中 ， 将 有 10 
个 元 素 需要 存储 到 红 黑 树 窗口 中 ， 每 个 元 素 的 关键 字 是 简单 的 整 型 ， 分 别 为 1、6、8、11、 
13、15、17、22、25、27， 以 下 的 例子 中 都 会 使 用 到 这 10 个 市 点 数据 。 


7.5.1 为 什么 设计 ngx rbtree t 红 黑 树 
上 文 介绍 的 容器 都 是 顺序 容器 ， 它 们 的 检索 效率 通常 情况 下 都 比较 差 ， 一般 只 能 人 遍历 检 


索 指定 元 素 。 当 需要 容器 的 检索 速度 很 快 ， 或 者 需要 文 持 范 围 但 询 时 ，ngx_rbtree_ t 红 黑 树 容 
名 是 一 个 非常 好 的 选择 。 





红 黑 树 实际 上 是 一 种 自 平 衡 二 又 查 找 树 ， 但 什么 是 二 叉 树 昵 ?二叉树 是 每 个 市 上 最 多 有 
两 个 子 树 的 树 结构 ， 每 个 节点 都 可 以 用 于 存储 数据 ， 可 以 由 任 1 个 节点 访问 它 的 左右 子 树 或 
者 父 节 点 。 





那么 ， 什 么 是 二 又 碍 找 树 呢 ? 二 又 查找 树 或 者 是 一 柠 空 树 ， 或 者 是 具有 下 列 性 质 的 二 又 
树 。 


` 每 个 节点 都 有 一 个 作为 查找 依据 的 关键 码 (key) ， 所 有 节点 的 关键 码 互 不 相同 。 
` 左 子 树 (如 果 存 在 ) 上 所 有 节点 的 关键 码 都 小 于 根 节点 的 关键 码 。 
“ 右 子 树 〈 如 果 存 在 ) 上 所 有 节点 的 关键 码 都 大 于 根 节 点 的 关键 码 。 


. 左 子 树 和 右 子 树 也 是 二 又 查找 树 。 
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这 样 ， 一 棵 二 又 查找 树 的 所 有 元 素 节点 都 是 有 序 的 。 在 二 又 树 的 形态 比较 平衡 的 情况 
下 ， 它 的 检索 效率 很 高 ， 有 点 类 似 于 二 分 法 检索 有 序数 组 的 效率 。 一 般 情 况 下 ， 碍 询 复杂 度 
是 与 目标 节点 到 根 节点 的 距离 〈 即 深度 ) 有 关 的 。 然 而 ， 不 断 地 添加 、 删 除 节 点 ， 可 能 造成 
二 又 查找 树 形 态 非 常 不 平衡 ， 在 极端 情形 下 它 会 变 成 单 链 表 ， 检 索 效 率 也 就 会 变 得 低下 。 例 
如 ， 在 本 节 的 例子 中 ， 依 次 将 这 10 个 数据 1、6、8、11、13、15、17、22、25、27 添 加 到 一 
棵 普通 的 空 二 又 查找 树 中 ， 它 的 形态 如 图 7-6 所 示 。 














第 1 个 元 素 1 添 加 到 空 二 又 树 后 目 动 成 为 根 节 点 ， 而 后 陆续 添加 的 元 素 正 好 以 升序 递增 ， 
最 终 的 形态 必然 如 图 7-6 所 示 ， 也 就 是 相当 于 单 链表 了 ， 由 于 树 的 深度 太 大 ， 因 此 各 种 操作 
的 效率 都 会 很 低下 。 
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图 7-6 ” 首 通 的 二 又 查找 树 可 能 非常 不 平衡 


什么 是 目 平 衡 二 又 但 找 树 ? 在 不 断 地 问 二 又 查找 树 中 添 加、 删除 节 点 时 ， 二 又 碍 找 树 目 
吴 通过 形态 的 变换 ， 始 终 保 持 着 一 定 程度 上 的 平衡 ， 即 为 目 平衡 二 又 奉 找 树 。 目 平衡 二 又 碍 
找 树 只 是 一 个 概念 ， 它 有 许多 种 不 同 的 实现 方式 ， 如 AVL 树 和 红 黑 树 。 红 黑 树 是 一 种 自 平衡 
性 较 好 的 二 又 查找 树 ， 它 在 Linux 内 核 、C++ 的 STL 库 等 许多 场合 下 都 作为 核心 数据 结构 使 
用 。 本 节 讲 述 的 ngx_rbtree t 需 就 是 一 种 由 红 黑 树 实现 的 目 平 衡 二 又 奋 找 树 。 











ngx rbtree t 红 黑 树 容器 中 的 元 素 都 是 有 序 的 ， 它 支持 快速 的 检索 、 插 入 、 删 除 操作 ， 也 
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文 持 范 围 查 询 、 过 历 等 操作 ， 是 一 种 应 用 场景 非常 广泛 的 高 级 数据 结构 。 
7.$.2 ” 红 黑 树 的 特性 

本 市 讲述 红 黑 树 的 特性 ， 对 于 只 想 了 解 如 何 使 用 ngx_rbtree t 容 器 的 读者 ， 可 以 跳 过 本 
I 


红 黑 树 是 指 每 个 节点 都 囊 有 颜色 属性 的 二 又 查找 树 ， 其 中 颜色 为 红色 或 黑色 。 除 了 二 又 
查找 树 的 一 般 要 求 以 外 ， 对 于 红 黑 树 还 有 如 下 的 额外 的 特性 。 


特性 1: 节点 是 红色 或 黑色 。 
特性 2: 根 节点 是 黑色 。 
特性 3: 所 有 叶子 节点 都 是 黑色 〈 叶 子 是 NIL 节 点 ， 也 叫 “ 哨 兵 ”) 。 


特性 4: 每 个 红色 节点 的 两 个 子 节点 都 是 黑色 〈 每 个 时 子 节点 到 根 和 节点 的 所 有 路 径 上 不 
能 有 两 个 连续 的 红色 节点 ) 。 


特性 5: 从 任 一 节点 到 其 每 个 叶子 节点 的 所 有 简单 路 径 都 包含 相同 数目 的 黑色 节点 。 





这 些 约束 加 强 了 红 黑 树 的 关键 性 质 : 从 根 节点 到 叶子 节点 的 最 长 可 能 路 径 长 度 不 大 于 最 
短 可 能 路 径 的 两 倍 ， 这 样 这 个 树 大 致 上 束 是 平衡 的 了 。 因 为 二 又 树 的 操作 《比如 插入 、 删 除 
和 碍 找 某 个 值 的 最 慢 时 间 ) 都 是 与 树 的 高 度 成 比例 的 ， 以 上 的 5 个 特性 保证 了 树 的 高 度 《〈 最 
长 路 径 ) ， 所 以 它 完 全 不 同 于 普通 的 二 又 查找 树 。 





这 些 特性 为 什么 可 以 导致 上 述 结果 呢 ? 因为 特性 4 实际 上 决定 了 1 个 路 径 不 能 有 两 个 毗连 
的 红色 节点 ， 这 一 点 就 足够 了 。 最 短 的 可 能 路 径 都 是 黑色 节点 ， 最 长 的 可 能 路 径 有 交替 的 红 
色 节 点 和 黑色 节点 。 根 据 特性 5 可 知 ， 所 有 最 长 的 路 径 都 有 相同 数目 的 黑色 节点 ， 这 就 表明 
了 没有 路 径 能 大 于 其 他 路 径 长 度 的 两 倍 。 
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在 本 节 的 例子 中 ， 仍 然 按照 顺序 将 这 10 个 升序 递增 的 元 素 添 加 到 空 的 nex rbtree t 红 黑 树 
容器 中 ， 此 时 ， 我 们 会 发 现 根 节 点 不 是 第 1 个 添加 的 元 素 1， 而 是 元 素 11。 实 际 上 ， 依 次 添加 
元 素 1、6、8、11、13、15、17、22、25、27 后 ， 红 黑 树 的 形态 如 图 7-7 所 示 。 


troot 

+sentinel 

Hnsert 

+ngx rbtree init () 
+ngx rbtree insert () 
+ngx rbtree delete () 














哨兵 节 氮 






左右 子 树 





左右 子 树 





左右 子 树 


图 7-7 ngx_rbtree_t 红 黑 树 的 典型 图 示 (其 中 无 底 纹 节 点 表示 红色 ， 有 底 纹 节点 表示 黑色 ) 





如 图 7-7 所 示 的 是 一 棵 相对 平衡 的 树 ， 它 满足 红 黑 树 的 5 个 特性 ， 最 长 路 径 长 度 不 大 于 最 
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短路 径 的 2 倍 。 在 ngx_rbtree_t 红 黑 树 在 发 现 自身 满足 不 了 上 述 5 个 红 黑 树 特 性 时 ， 将 会 通过 旋 
转 ( 向 左旋 转 或 者 向 右 旋转 ) 子 树 来 使 树 达 到 平衡 。 这 里 不 再 讲述 红 黑 树 的 旋转 功能 ， 实 际 
上 它 非常 简单 ， 读 者 可 以 通过 ngx rbtree left rotate 和 ngx rbtree right rotate 方 法 来 了 解 旋转 功 
能 的 实现 。 


7.5.3” 红 黑 树 的 使 用 方法 


红 黑 树 容 器 由 ngx rbtree t 结 构 体 承载 ，ngx_rbtree t 的 成 员 和 它 相 关 的 方法 在 图 7-7 中 可 
以 看 到 ， 下 面 进行 详细 介绍 。 首 先 ， 需 要 了 解 一 下 红 黑 树 的 节点 结构 ， 如 图 7-8 所 示 。 


ngx rbtree node { 


+ key 


+ left 
+ right 
+ parent 
+ color 
+ data 
gx rbt red() 
gx rbt black() 
gx rbt 1s red() 
rbt 1s black() 
Ibt copy color() 
gx rbtree sentinel init() 


gx rbtree min() 





图 7-8” 红 黑 树 节点 的 结构 体 及 其 提供 的 方法 


ngx_rbtree_node tt 结构 体 用 来 表示 红 黑 树 中 的 一 个 节点 ， 它 还 提供 了 7 个 方法 用 来 操作 市 
点 。 下 面 了 解 一 下 ngx rbtree_ node tt 结构 体 的 定义 ， 代 码 如 下 。 








typedef ngx uint t ngx rbtree key 七 
typedef struct ngx rbtree node s ngx rbtree node t; 
struct ngx rbtree node s { 

// 无 符号 整 型 的 关键 字 








ngx rbtree key 七 key; 

// 左 子 节点 

ngx_ rbtree node t *]EFt > 
// 右 子 节点 

ngx rbtree node t *right; 
// 父 节点 

ngx rbtree node t *parent; 


// 节点 的 颜色 ， 


0 表示 黑色 ， 


Ui Char COLOrE: 


// 仅 


1 个 字 节 的 节点 数据 。 由 于 表示 的 空间 太 小 ， 所 以 一 般 很 少 使 用 


u char data; 





ngx_rbtree_node t 是 红 黑 树 实 现 中 必须 用 到 的 数据 结构 ， 一 般 我 们 把 它 放 到 结构 体 中 的 
第 1 个 成 员 中 ， 这 样 方 便 把 自 定义 的 结构 体 强 制 转换 成 ngx_rbtree_node t 类 型 。 例 如 : 








typedef struct { 
/* 一 般 都 将 


ngx_rbtree _node 七 节点 结构 体 放 在 自 定义 数据 类 型 的 第 


1 位 ， 以 方便 类 型 的 强制 转换 





ngx_ rbtree node t node; 
ngx uint t num; 
} TestRBTreeNode; 








如 果 这 里 希望 容器 中 元 素 的 数据 类 型 是 TestRBTreeNode， 那 么 只 需要 在 第 1 个 成 员 中 放 
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上 ngx_rbtree_node t 类 型 的 node 妈 可。 在 调用 图 7-7 中 ngx_rbtree {t 容 右 所 提供 的 方法 时 ， 需 要 
的 参数 都 是 ngx_rbtree_node t 类 型 ， 这 时 将 TestRBTreeNode 类 型 的 指针 强制 转换 成 


ngx rbtree node tN 可 。 





ngx rbtree_node tt 结构 体 中 的 key 成 员 是 每 个 红 黑 树 节 点 的 关键 字 ， 它 必须 是 整 型 。 红 黑 
树 的 排序 主要 依据 key 成 员 〈( 当 然 ， 自 定义 ngx rbtree insert pt 方法 后 ， 节 点 的 其 他 成 员 也 可 
以 在 key 排 序 的 基础 上 影响 红 黑 树 的 形态 ) 。 在 图 7-7 所 示例 子 中 ，1、6、8、11、13、15、 
17、22、25、27 这 些 数字 都 是 每 个 节点 的 key 关 键 字 。 


下 面 看 一 下 表示 红 黑 树 的 ngx_rbtree_t 结 构 体 是 如 何 定义 的 ， 代 码 如 下 。 





typedef struct ngx rbtree s ngx rbtree t; 
/* 为 解决 不 同 节点 含有 相同 关键 字 的 元 素 冲 突 问题 ， 红 黑 树 设置 了 





ngx rbtree insert pt 指针 ， 这 样 可 灵活 地 添加 冲突 元 素 





六 

typedef void (ngx rbtree insert pt) (ngx rbtree node t root, 
ngx rbtree node t node, ngx rbtree node t *sentinel); 

struct ngx rbtree s { 


// 指向 树 的 根 节 点 。 注 意 ， 根 节点 也 是 数据 元 素 








ngx rbtree node t *root; 


// 指向 


NIL 哨 兵 节 点 


ngx rbtree node t *sentinel; 
// 表示 红 黑 树 添加 元 素 的 函数 指针 ， 它 决定 在 添加 新 节点 时 的 行为 究 况 是 蔡 换 还 是 新 增 


ngx rbtree insert pt insert; 


}; 











在 上 上 段 代 码 中 ，ngx_rbtree t 结 构 体 的 root 成 员 指 同根 节点 ， 而 sentinel 成 员 指 问 哨兵 市 
点 ， 这 很 清晰 。 然 而 ，insert 成 员 作 为 一 个 ngx_rbtree_insert pt 类 型 的 函数 指针 ， 它 的 意义 在 
哪里 呢 ? 








红 黑 树 是 一 个 通用 的 数据 结构 ， 它 的 节点 (或 者 称 为 容器 的 元 素 ) 可 以 是 包含 基本 红 黑 
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树 节 点 的 任意 结构 体 。 对 于 不 同 的 结构 体 ， 很 多 场合 下 是 允许 不 同 的 节点 拥有 相同 的 关键 字 
的 《参见 图 7-8 中 的 key 成 员 ， 它 作为 无 符号 整 型 数 时 表示 树 节 点 的 关键 字 ) 。 例 如 ， 不 同 的 
字符 串 可 能 会 散 列 出 相同 的 关键 字 ， 这 时 它们 在 红 黑 树 中 的 关键 字 是 相同 的 ， 然 而 它们 又 是 
不 同 的 市 点 ， 这 样 在 添加 时 残 不 可 以 履 盖 原 有 同名 关键 字 节 点 ， 而 是 作为 新 插入 的 闻 点 存 
在 。 因 此 ， 在 添加 元 素 时 ， 需 要 考虑 到 这 种 情况 。 将 添加 元 和 际 的 方法 抽象 出 
ngx_Tbtree_insert pt 函数 指针 可 以 很 好 地 实现 这 一 思想 ， 用 户 也 可 以 灵活 地 定义 上 自己 的 行为 。 
Nginx 帮 助 用 户 实现 了 3 种 简单 行为 的 添加 节点 方法 ， 见 表 7-4。 

















表 7-4 Nginx 为 红 黑 树 已 经 实现 好 的 3 种 数据 添加 方法 


方法 名 执行 意义 





void ngx_ rbtree_insert_value root 是 红 黑 树 容器 的 指针 ; node 是 待 | 向 红 黑 树 添加 数据 节点 ， 每 个 
(ngx_ rbtree node t *root, 添加 元 素 的 ngx_rbtree node t 成 员 的 指 | 数据 节 点 的 关键 字 都 是 唯一 的 ， 
ngx rbtree node t *node, 针 ; sentinel 是 这 棵 红 黑 树 初始 化 时 哨兵 | 不 存在 同一 个 关键 字 有 多 个 节点 


ngx rbtree node t *sentinel) 生 点 的 指针 的 问题 

root 是 红 黑 树 容 带 的 指针 ; node 是 符 
添加 元 素 的 ngx rbtree node t 成 员 的 | 回 红 黑 树 添加 数据 节点 ， 每 个 
指针 ， 它 对 应 的 关键 字 是 时 间或 者 时 间 | 数据 节点 的 关键 字 表 示 时 间或 者 
差 ， 可 能 是 负数 ; sentinel 是 这 棵 红 黑 树 | 时 间 差 
初始 化 时 的 哨兵 节点 

root 是 红 黑 树 容 天 的 指针 ; node 是 待 | 回 红 黑 树 添加 数据 节点 ， 每 个 
添加 元 素 的 ngx_str node t 成 员 的 指针 | 数据 节点 的 关键 字 可 以 不 是 唯一 
( ngx_rbtree_node t 类 型 会 强制 转化 为 | 的 ,但 它们 是 以 字符 串 作为 唯 
ngx_ str node t 类 型 ) ; sentinel 是 这 棵 红 | 的 标识 ， 存 放 在 ngx_str node ft 
黑 树 初始 化 时 哨兵 节点 的 指针 结构 体 的 str 成 员 中 


void ngx Tbtree insert _ timer value 





(ngx_ rbtree_ node t *root, 
ngx rbtree node t *node. 


ngx rbtree node t *sentinel) 


Vold nex_ str rbtree insert Value 
(ngx Ibtree node t *temp, 
ngx rbtree node t *node, 


ngx rbtree node t *sentinel) 





表 7-4 中 ngx_str_rbtree_insert_value 函 数 的 应 用 场景 为 : 节点 的 标识 符 是 字符 串 ， 红 黑 树 
的 第 一 排序 依据 仍然 是 节点 的 key 关 键 字 ， 第 二 排序 依据 则 是 节点 的 字符 串 。 因 此 ， 使 用 
ngx_str_rbtree_insert_value 时 表示 红 黑 树 节点 的 结构 体 必须 是 ngx_str_node t， 如 下 所 示 。 








typedef struct { 
ngx_ rbtree node t node; 
ngx_str t str; 
} ngx str node t; 





同时 ， 对 于 ngx_str_node t 闻 点 ，Nginx 还 提供 了 ngx_str_rbtree_lookup 方 法 用 于 检索 红 
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树 节 点， 下 面 来 看 一 下 它 的 定义 ， 代 码 如 下 。 





ngx str node t *ngx str rbtree lookup (ngx rbtree t rbtree, ngx str t name, uint32 t hash); 











其 中 ，hash 参 数 是 要 但 询 节 扣 的 key 关 键 子 ， 而 name 是 要 查询 的 字符 串 〈 解 决 不 同 字 符 串 
对 应 相同 key 关 键 字 的 问题 ， 返 回 的 是 查询 到 的 红 黑 树 市 点 结构 体 。 


关于 红 黑 树 操 作 的 方法 见 表 7-5。 


表 7-5 红 黑 树 容器 提供 的 方法 


方法 名 执行 意义 


tree 是 红 黑 树 容 吉 的 指针 ; s 是 哨兵 | 初始 化 红 黑 树 ， 包 括 初 始 化 根 节 





ngx_ rbtree_init(tree, s. i) 入 点 的 指针 ; i 是 ngx_rbtree_insert_pt| 点 、 哨 兵 节 点 、negx_rbtree_insert_pt 
类 型 的 节点 添加 方法 ， 有 具体 见 表 7-4 | 节点 添加 方法 
void ngx_rbtree_insert(ngx_rbtree t| tree 是 红 黑 树 容器 的 指针 ; node 是 | 向 红 黑 树 中 添加 节点 ， 该 方法 会 
*tree, ngx_rbtree_ node t+ *node) 需要 添加 到 红 黑 树 的 节点 指针 通过 旋转 红 黑 树 保持 树 的 平衡 
void ngx_rbtree_delete(ngx_rbtree t| tree 是 红 黑 树 容 融 的 指针 ; node 是 | 从 红 黑 树 中 删除 节点 ， 该 方法 会 


*tree, DgX_Tbtree node t *node) 红 黑 树 中 需要 删除 的 节点 指针 通过 旋转 红 黑 树 保持 树 的 平衡 


在 初始 化 红 黑 树 时 ， 需 要 先 分 配 好 保存 红 黑 树 的 ngx_rbtree t 结 构 体 ， 以 及 
ngx rbtree_node t 类 型 的 哨兵 节点 ， 并 选择 或 者 目 定 义 ngx rbtree insert pt 类 型 的 节点 添加 函 
数 。 


对 于 红 黑 树 的 每 个 节点 来 说 ， 它 们 都 具备 表 7-6 所 列 的 7 个 方法 ， 如 果 只 是 想 了 解 如 何 使 
用 红 黑 树 ， 那 么 只 需要 了 解 ngx_rbtree_min 方 法 。 


表 7-6 ” 红 黑 树 节 点 提供 的 方法 
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方 污 


node 是 红 黑 树 中 ngx_rbtree node f 


eT 设置 node 节点 的 颜色 为 红色 
类 型 的 节点 指针 


ngx rbt red(node) 

node 是 红 黑 树 中 ngx_rbtree node t 
类 型 的 节点 指针 

node 是 红 黑 树 中 ngx_rbtree node t| 奉 node 节 点 的 颜色 为 红色 ， 则 返回 非 0 
类 型 的 节点 指针 数值 ， 否 则 返回 0 

node 是 红 黑 树 中 ngx rbtree node t| 若 node 节点 的 颜色 为 黑色 ， 则 返回 非 0 
类 型 的 节点 指针 数值 ， 和 否则 返回 0 


ngx_rbt_black(node) 设置 node 节点 的 颜色 为 黑色 


ngx rbt 1s red(node) 


ngx rbt 1s_ black(node) 


nl1、n2 都 是 红 黑 树 中 ngx rbtree_ 


node t 类 型 的 节点 指针 


ngx_ rbt_copy_color(n1. n2) 将 n2 节点 的 颜色 复制 到 nl 节点 


ngx rbtree node t* i 

node 是 红 黑 树 中 ngx rbtree node ft 
类 型 的 节点 指针 ; sentinel 是 这 棵 红 黑 
树 的 哨兵 节点 


找到 当前 节点 及 其 子 树 中 的 最 小 节点 
(按照 key 关键 字 ) 


ngx rbtree_ min 
(ngx Ibtree node t *node, 
ngx rbtree node t *sentinel) 


node 是 红 黑 树 中 ngx rbtree node t| 初始 化 哨兵 节点 ， 实 际 上 就 是 将 该 节点 


i Ttee: Sentnel mt(noOde) | ss i 
Ea 二 于 类 型 的 节点 指针 颜色 置 为 黑色 








表 7-5 中 的 方法 大 部 分 用 于 实现 或 者 扩展 红 黑 树 的 功能 ， 如 果 只 是 使 用 红 黑 树 ， 那 么 一 
般 情 况 下 只 会 使 用 ngx _rbtree_min 方 法 。 


本 节 介 绍 的 方法 或 者 结构 体 的 简单 用 法 的 实现 可 参见 7.5.4 节 的 相关 示例 。 


7.$.4 ”使 用 红 黑 树 的 简单 例子 





本 市 以 一 个 人 简 蛙 的 例子 来 说 明 如 何 使 用 红 黑 树 容 如 。 首 先 在 栈 中 分 配 rbtree 红 黑 树 容 右 
结构 体 以 及 哨兵 节点 sentinel〈 当 然 ， 也 可 以 使 用 内 存 池 或 者 从 进程 堆 中 分 配 ) ， 本 例 中 的 市 
扩 完 全 以 key 关 键 字 作为 每 个 市 点 的 唯一 标识 ， 这 样 就 可 以 采用 预 设 的 ngx_rbtree_insert_value 
方法 了 。 最 后 可 调用 ngx_rbtree_init 方 法 初始 化 红 黑 树 ， 代 码 如 下 所 示 。 





ngx rbtree t rbtree; 
ngx_ rbtree node 七 sentinel; 
ngx rbtree init(&rbtree, &sentinel, ngx rbtree insert value); 











本 例 中 树 节点 的 结构 体 将 使 用 7.5.3 节 中 介绍 的 TestRBTreeNode 结 构 体 ， 树 中 的 所 有 节点 
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都 取 自 图 7-7， 每 个 元 素 的 key 关 键 字 按 照 1、6、8、11、13、15、17、22、25、27 的 顺序 一 一 
向 红 黑 树 中 添加 ， 代 码 如 下 所 示 。 





TestRBTreeNode rbTreeNode[10]; 




















rbTreeNode[0] .num = 1; 
rbTreeNode[l1l] .num = 6; 
rbTreeNode[2] .num = 8; 
rbTreeNode[3] .num = 11; 
rbTreeNode[4] .num = 13; 
rbTreeNode[5] .num = 15; 
rbTreeNode[6] .num = 17; 
rbTreeNode[7] .num = 22; 
rbTreeNode[8] .num = 25; 
rbTreeNode[9] .num = 27; 


for (i = 0; i < 10; i++) 
{ 
rbTreeNodel[il.node.key = rbTreeNode[i] .num; 
ngx rbtree insert(&rbtree,&rbTreeNodel[i].node); 








以 这 种 顺序 添加 完 的 红 黑 树 形态 如 图 7-7 所 示 。 如 果 和 需要 找 出 当前 红 黑 树 中 最 小 的 节 
点 ， 可 以 调用 ngx_rbtree_min 方 法 获取 。 





ngx_ rbtree node t *tmpnode = ngx rbtree minl(rbtree.root, &sentinel); 





SS 


当然 ， 参 数 中 如 果 不 使 用 根 节 点 而 是 使 用 任 一 个 市 点 也 是 可 以 的 。 下 面 来 看 一 下 如 何 检 
索 1 个 和 节点， 虽然 Nginx 对 此 并 没有 提供 预 设 的 方法 〈 仅 对 字符 串 类 型 提供 了 
ngx_str_rbtree_lookup 检 索 方法 ) ， 但 实际 上 检索 是 非常 简单 的 。 下 面 以 寻找 key 天 键 字 为 13 
的 布点 为 例 来 加 以 说 明 。 








ngx uint t lookupkey = 13; 
tmpnode = rbtree.root; 
TestRBTreeNode *lookupNode; 


while (tmpnode != &sentinel) { 
if (lookupkey != tmpnode->key) { 
// 根据 


key 关 键 字 与 当前 节点 的 大 小 比较 ， 决 定 是 检索 左 子 树 还 是 右 子 树 


tmpnode = (lookupkey < tmpnode->key) tmpnode->left : tmpnode->right; 
continue; 


} 
// 找到 了 值 为 


13 的 树 节 点 


口 由 掉 由 有 有 和 所 掉 由 http' /wNv inuxorobe. con 





lookupNode = (TestRBTreeNode *) tmpnode; 
break; 





} 





从 红 黑 树 中 删除 1 个 节点 也 是 非常 简单 的 ， 如 把 刚刚 找到 的 值 为 13 的 节点 从 rbtree 中 删 
除 ， 只 需 调 用 ngx rbtree_delete 方 法 。 








ngx rbtree delete(&rbtree,&lookupNode->node); 








7.5.5 ”如 何 自 定义 添加 成 员 方 法 





由 于 节点 的 key 关 键 字 必须 是 整 型 ， 这 导致 很 多 情况 下 不 同 的 节点 会 具有 相同 的 key 关 键 
字 。 如 果 不 和 希望 出 现 具 有 相同 key 关 键 字 的 不 同 节 点 在 向 红 黑 树 添 加 时 出 现 履 盖 原 节点 的 情 
况 ， 就 需要 实现 自 有 的 ngx rbtree insert pt 方法 。 





许多 Nginx 模 块 在 使 用 红 黑 树 时 都 自 定 义 了 ngx rbtree insert pt 方法 〈 如 geo、filecache 模 
块 等 ) ， 本 节 以 7.5.3 节 中 介绍 过 的 ngx str rbtree insert value 为 例 ， 来 说 明 如 何 定义 这 样 的 方 
法 。 先 看 一 下 ngx str rbtree insert value 的 实现 。 代 码 如 下 。 





void 
ngx str rbtree insert Value (ngx rbtree node 七 *temp, 
ngx rbtree node t node, ngx rbtree node t sentinel) 








{ 


ngx str node t n, t; 

ngx rbtree node 七 **p; 

for (277 ) { 
n= (ngx str node 七 ) node; 
t= (ngx str noae t ) temp; 
// 首先 比较 


key 关 键 字 ， 红 黑 树 中 以 


key 作 为 第 一 索引 关键 字 


if (node->key != temp->key) { 
// 左 子 树 节点 的 关键 节 小 于 右 子 树 





p= (node->key < temp->key) &temp->left : &temp->right; 
} 
// 者 
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key 关 键 字 相同 时 ， 以 字符 串 长 度 为 第 二 索引 关键 字 


else if (n->str.len != t->str.len) { 


// 左 子 树 节点 字符 串 的 长 度 小 于 右 子 树 





p= (n->str.len < t->str.len) &temp->left : &temp->right; 
} else { 


// key 关 键 字 相同 且 字 符 串 长 度 相 同时 ， 再 继续 比较 字符 串 内 容 


p= (ngx memcmp (n->str.data, t->str.data, n->str.len) < 0) &temp->left : &temp->right; 


} 
// 如 果 当 前 节点 


Pp 是 哨兵 节点 ， 那 么 跳出 循环 准备 插入 节点 


if (*p == sentinel) { 
break; 
} 
// Pp 节点 与 要 插入 的 节点 具有 相同 的 标识 符 时 ， 必 须 窗 盖 内 容 


temp = p; 
} 
p = node; 
// 置 播 入 节点 的 父 节点 


node->parent = temp; 
// 左右 子 节点 都 是 哨兵 节点 





node->left = sentinel; 
node->right = sentinel; 


/* 将 节点 颜色 置 为 红色 。 注 意 ， 红 黑 树 的 





ngx_Frbtree_insett 方 法 会 在 可 能 的 旋转 操作 后 重 置 该 节点 的 颜色 


3 
ngx rbt red (node); 
} 





可 以 看 到 ， 该 代码 与 7.5.4 市 中 介绍 过 的 检索 节点 代码 很 相似 。 它 所 要 处 理 的 主要 问题 就 
是 当 key 关 键 字 相同 时 ， 继 续 以 何 种 数据 结构 作为 标准 来 确定 红 黑 树 节点 的 唯一 性 。Nginx 中 
己 经 实现 的 诸多 ngx_rbtree_insert_pt 方 法 都 是 非常 相似 的 ， 读 者 完全 可 以 参照 
ngx_str_rbtree_insert_value 方 法 来 自 定 义 红 黑 树 节点 添加 方法 。 
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7.6 negx radix tree t 基 数 树 





基数 树 也 是 一 种 二 又 碍 找 树 ， 然 而 它 却 不 像 红 黑 树 一 样 应 用 广泛 《目前 官方 模块 中 仪 
geo 模 块 使 用 了 基数 树 ) 。 这 是 因为 ngx_radix_tree _t 基 数 树 要 求 存 储 的 每 个 节点 都 必须 以 32 位 
整 型 作为 区 别 任 意 两 个 节点 的 唯一 标识 ， 而 红 黑 树 则 没有 此 要 求 。ngx_radix tree _t 基 数 树 与 
红 黑 树 不 同 的 男 一 个 地 方 ，ngx_radix_tree {基数 树 会 负 贡 分 配 每 个 市 点 占用 的 内 存 。 因 此 ， 
每 个 基数 树 市 点 也 不 再 像 红 黑 树 中 那么 灵 可 以 是 任意 包含 ngx_rbtree_node 成 员 的 结 
构 体 。 基 数 树 的 每 个 节点 中 可 以 存储 的 值 只 是 1 个 指针 ， 它 指 问 实际 的 数据 。 











本 节 将 以 一 棵 完整 的 ngx_radix tree _t 基 数 树 来 说 明基 数 树 的 原理 和 用 法 ， 这 棵 树 的 深度 
为 3， 它 包括 以 下 4 个 节点 : 0X20000000、0X40000000、0X80000000、0Xc0000000。 这 里 书 
写成 十 六 进 制 是 为 了 便于 理解 ， 因 为 基数 树 实 际 是 按 二 进 制 位 来 建立 树 的 ， 上 面 4 个 节点 如 
果 转 换 为 十 进 制 无 符号 整 型 (也 就 是 7.6.3 节 例子 中 的 ngx_uint b ， 它 们 的 值 分 别 是 
536870912、1073741824、2147483648、2684354560; 如 果 转 换 为 二 进 制 ， 它 们 的 值 分 别 





为 : 00100000000000000000000000000000、01000000000000000000000000000000、 
10000000000000000000000000000000、11000000000000000000000000000000。 在 图 7-9 中 ， 
可 以 看 到 这 4 个 市 点 如 何 存 储 到 深度 为 3 的 基数 树 中 。 





7.6.1 ngx radix tree t 基 数 树 的 原理 


基数 树 具 备 二 又 得 找 树 的 所 有 优点 : 基本 操作 速度 快 〈 如 检索 、 插 入 、 删 除 节 点 ) 、 文 
持 范 围 查 询 、 文 持 过 有 历 操作 等 。 但 基数 树 不 像 红 黑 树 那 样 会 通过 目 身 的 旋转 来 达到 平衡 ， 基 
数 树 是 不 管 树 的 形态 是 否 平衡 的 ， 因 此 ， 生 插入 节点 、 删 除 节 损 的 速度 要 比 红 黑 树 快 得 多 ! 
那么 ， 基 数 树 为 什么 可 以 不 管 树 的 形态 是 否 平衡 呢 ? 





红 黑 树 是 通过 不 同 节点 间 key 关 键 字 的 比较 来 决定 树 的 形态 ， 而 基数 树 则 不 然 ， 它 每 一 
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个 节点 的 key 关 键 字 已 经 决定 了 这 个 节点 处 于 树 中 的 位 置 。 决 定 节点 位 置 的 方法 很 简单 ， 先 
将 这 个 节点 的 整 型 关键 字 转 化 为 二 进 制 ， 从 左 向 右 数 这 32 个 位 ， 遇 到 0 时 进入 左 子 树 ， 遇 到 1 
时 进入 右 子 树 。 因 此 ，ngx radix tree t 树 的 最 大 深度 是 32。 有 时 ， 数 据 可 能 仅 在 全 部 整 型 数 
范围 的 某 一 小 段 中 ， 为 了 减少 树 的 高 度 ，ngx radix tree t 又 加 入 了 掩 码 的 概念 ， 掩 码 中 为 1 的 
位 节点 关键 字 中 有 效 的 位 数 同时 也 决定 了 树 的 有 效 高 度 。 例 如 ， 掩 码 为 
11100000000000000000000000000000 (也 就 是 0Xe0000000〉 时 ， 表 示 树 的 高 度 为 ?。 如 果 1 个 
节点 的 关键 字 为 0XOffffftff， 那 么 实际 上 对 于 这 棵 基数 树 而 言 ， 它 的 节点 关键 字 相 当 于 
0X00000000， 因 为 掩 码 决定 了 仪 前 3 位 有 效 ， 并 且 它 也 只 会 放 在 树 的 第 三 层 节点 中 。 





如 图 7-9 所 示 ，0X20000000 这 个 节点 插 到 基数 树 后 ， 由 于 掩 码 是 0Xe0000000， 因 此 它 决 
定 了 所 有 的 节点 都 将 放 在 树 的 第 三 层 。 下 面 结合 掩 码 看 看 节点 是 如 何 根据 关键 字 来 决定 其 在 
树 中 的 位 置 的 。 掩 码 中 有 3 个 1， 将 节点 的 关键 字 0X20000000 转 化 为 二 进 制 再 取 前 3 位 为 
001， 然 后 分 3 步 决 定 节点 的 位 置 。 








. 首先 找到 根 节 点 ， 取 010 的 第 1 位 0， 表 示 选 择 左 子 树 。 
第 2 位 为 0， 表 示 再 选择 左 子 树 。 


第 3 位 为 1， 表 示 再 选择 右 子 树 ， 此 时 的 节点 就 是 第 三 层 的 节点 ， 这 时 会 用 它 来 存储 
0X20000000 这 个 节点 。 
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ngx radix tree t 


+right 十 S1Ze 

+left t+ngx radix tree create() 

+parent tngx radix32 tree insert () 

P-value +ngx radix32 tree_delete () 
tngx radix32 tree find() 


用 户 自 定义 的 数据 结构 





ngx radix node t 节点 
图 7-9 3 层 基 数 树 示意 图 


ngx radix tree t 基 数 树 的 每 个 节点 由 ngx radix node tt 结构 体 表示 ， 代 码 如 下 所 示 。 





typedef struct ngx radix node s ngx radix node t; 
struct ngx radix node s { 


// 指向 右 子 树 ， 如 果 没 有 右 子 树 ， 则 值 为 





null 空 指针 


ngx radix node t *right; 


// 指向 左 子 树 ， 如 果 没 有 左 子 树 ， 则 值 为 
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null 空 指针 


ngx radix node t *left; 


// 指向 父 节点 ， 如 果 没 有 父 节 点 ， 则 (如 根 节点 ) 值 为 


null 空 指针 


ngx radix node t parent; 


/value 存 储 的 是 指针 的 值 ， 它 指向 用 户 定义 的 数据 结构 。 如 果 这 个 节点 还 未 使 用 ， 


value 的 值 将 是 


NGX RADIX NO VALUE */ 
uintptr t value; 


}; 








如 图 7-9 所 示 ，value 字 段 指向 用 户 自 定义 的 、 有 意义 的 数据 结构 。 另 外 ， 基 数 树 也 不 像 
红 黑 树 一 样 还 有 哨兵 和 节点。 基数 树 节 点 的 left 和 right 都 是 有 可 能 为 null 空 指针 的 。 





与 红 黑 树 不 同 的 是 ， 红 黑 树 容器 不 负责 分 配 每 个 树 节 点 的 内 存 ， 而 ngx_radix_tree_t 基 数 
树 则 会 分 配 ngx_radix_node tt 结构 体 ， 这 样 使 用 ngx_radix_node {基数 树 时 就 会 更 简单 一 些 。 但 
ngx_radix node t 基 数 树 是 如 何 管理 这 些 ngx radix node t 结 构 体 的 内 存 呢 ? 下 面 来 看 一 下 
ngx_radix_node t 容 器 的 结构 ， 代 码 如 下 。 





typedef struct { 
// 指向 根 节点 


ngx radix node t *root; 


// 内 存 池 ， 它 负责 给 基数 树 的 节点 分 配 内 存 


ngx Pool t Poo 
/管理 已 经 分 配 但 暂时 未 使 用 (不 在 树 中 ) 的 节点 ， 


free 实 际 上 是 所 有 不 在 树 中 节点 的 单 链表 


ngx radix node t free; 


// 已 分 配 内 存 中 还 未 使 用 内 存 的 首 地 址 


char *start; 


// 已 分 配 内存 中 还 未 使 用 的 内 存 大 小 


TiNNNNinNnnn http://wWwWw linuxorobe.con 





size 七 size; 
} ngx radix tree t; 





上 面 的 pool 对 象 用 来 分 配 内 存 。 每 次 删除 1 个 节点 时 ，ngx_radix_tree_ {基数 树 并 不 会 释放 
这 个 节点 占用 的 内 存 ， 而 是 把 它 添加 到 free 单 链表 中 。 这 样 ， 在 添加 新 的 节点 时 ， 会 首先 查 
看 free 中 是 否 还 有 节点 ， 如 果 free 中 有 未 使 用 的 节点 ， 则 会 优先 使 用 ， 如 果 没 有 ， 就 会 再 从 

pool 内 存 池 中 分 配 新 内 存 存储 节点 。 








对 于 ngx radix tree _t 绪 构 体 来 说 ， 仅 从 使 用 的 角度 来 看 ， 我 们 不 需要 了 解 pool、free、 
start、Size 这 些 成 员 的 意义 ， 仅 了 解 如 何 使 用 root 根 节点 即 可 。 





7.6.2 ”基数 树 的 使 用 方法 


相 比 于 红 黑 树 ，ngx radix tree t 基 数 树 的 使 用 方法 要 人 简单 许多 ， 只 需 表 7-7 中 列 出 的 4 个 
方法 即 可 简单 地 操作 基数 树 。 


表 7-7 ngx_radix_tree_t 基 数 树 提供 的 方法 


方法 名 执行 意义 
pool 是 内 存 池 指 针 ，preallocate 是 预 | 用 来 创建 ngx radix tree t 基 
分 配 的 基数 树 节 点 数 ， 如 果 传 递 的 值 | 数 树 。 如 果 创 建成 功 ， 则 返回 
为 -1， 那 么 将 会 根据 当前 操作 系统 中 |ngx_radix tree t 结 构 体 的 指针 ; 
-个 页 面 的 大 小 来 预 分 配 基 数 树 节点 ”| 如果 失 败 ， 则 返回 NULL 空 指针 
表示 问 基 数 树 中 插入 1 个 节 


ngx radix tree t *nex radix tree create 
(ngx pool t *pool. 


ngx int t preallocate) 


ngx int tnex radix32tree insert tree 是 ngx radix tree t 基 数 树 结构 y a 
wi be ese we sea | 发 。 吉 时 成 轨 ， 则 最 加 angse 
(ngx radix tree t *tree, 体 的 指针 ，key 是 待 插入 节点 的 关键 OK ; 如果 内 存 池 中 无 法 分 配 
= 性 > vB ET yh Caz sp ; XH V1 外 弃 全 HL 
uint32 t key. 5 mask 为 大 键 字 掩 全 \ 决 /FE key 大 [mi 够 的 Px | ]| 放 : 反 | | NGX 
a EE 要 De EE 中 多 23 FE > 1 ] 芭 口 X 
uint32_t mask. 键 字 有 效 位 数 以 及 树 的 深度 )，value 7 
Rt i ID 二 说 ERROR ; 如 果 掩 码 设置 错误 ， 
uintptr_t value) 是 这 个 关键 字 对 应 数据 结构 的 指针 





则 可 能 返回 NGX_BUSY 
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万 二 RT 

tree 是 tree t 基 数 树 结构 | 表示 从 基数 树 中 删除 1 个 
体 的 指针 ，key 是 待 删除 节点 的 关键 | 点 。 如 果 删 除 成 功 ， 则 返回 
字 ，mask 为 关键 : 码 (决定 key 关 |NGX OK ; 如 果 删 除 失败 ， 则 
键 字 有 效 位 数 ) 返回 NGX_ERROR 

表示 在 基数 树 中 查询 1 个 节 
点 ， 对 于 返回 的 uintptr t 类 型 

tree 是 ngx_radix_tree t 基 数 树 结 构 | 的 指针 地 址 ， 可 以 将 其 强制 转 
体 的 指针 ，key 是 待 查询 节点 的 关键 字 | 化 为 实际 数据 结构 的 指针 来 使 
用 。 如 果 没 有 查询 到 ， 则 会 返 
器 NGX RADIX NO VALUE 


+44- 
J 


ngx int tngx radix32tree delete 
(ngx radix tree t *tree, 


uint32 t key. uint32 t mask) 


uintptr t ngx radix32tree find 
(ngx radix tree t *tree， 
uint32 t key) 





7.6.3 ”使 用 基数 树 的 例子 


本 节 以 图 7-9 中 的 基数 树 为 例 来 构造 radixTree 这 棵 基数 树 。 首 先 ， 使 用 
ngx_Tadix tree_create 方 法 创建 基数 树 ， 代 码 如 下 。 





ngx radix tree t * radixTree = ngx radix tree _ create (cf->pool, -1); 





将 预 分 配 节 点 简单 地 设置 为 -1， 这 样 pool 内 存 池 中 束 会 只 使 用 1 个 页 面 来 尽 可 能 地 分 配 
基数 树 市 皮 。 接 下 来 ， 按 照 图 7-9 构 造 4 个 市 点 数据 ， 这 里 将 它们 所 使 用 的 数据 结构 简单 地 用 
无 符号 整 型 表示 ， 当 然 ， 实 际 使 用 时 可 以 是 任意 的 数据 结构 。 





ngx uint 七 testRadixValuel = 0x20000000; 
ngx uint t testRadixValue2 = 0x40000000; 
ngx uint t testRadixValue3 = 0x80000000; 
ngx uint t testRadixValue4 = 0xa0000000; 





接 下 来 将 上 述 节 点 添加 到 radixTree 基 数 树 中 ， 注 意 ， 掩 码 是 0xe0000000。 





int Ye 
rc = ngx radix32tree insert (radixTree, 

Ox20000000, 0xe0000000, (uintptr 七 ) &testRadixValuel); 
rc = ngx radix32tree insert (radixTree, 

Ox40000000, Oxe0000000, (uintptr 七 ) &testRadixValue2); 
rc = ngx radix32tree insert (radixTree, 

Ox80000000, 0xe0000000, (uintptr 七 ) &testRadixValue3); 
rc = ngx radix32tree insert (radixTree, 

Oxa0000000, Oxe0000000, (uintptr 七 ) &testRadixValue4); 











下 面 来 试 着 调用 ngx radix32tree find 查询 节点 ， 代 人 码 如 下 。 





ngx uint tx PRadixValue = (ngx uint t *) ngx radix32tree find( radixTree, 0x80000000); 





注意 ， 如 果 没 有 查询 到 ， 那 么 返回 的 pRadixValue 将 会 是 NGX RADIX NO VALUE。 


下 面 调 用 ngx radix32tree_delete 删 除 1 个 节点 ， 代 码 如 下 。 





rc = ngx radix32tree delete(radixTree, 0xa0000000, Oxe0000000); 
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7.7 文 持 通配符 的 散 列 表 


散 列 表 《〈 也 叫 哈 希 表 ) 是 典型 的 以 空间 换 时 间 的 数据 结构 ， 在 一 些 合理 的 假设 下 ， 对 任 
意 元 素 的 检索 、 插 入 速度 的 期 望 时 间 为 0(1)， 这 种 高 效 的 方式 非常 适合 频 楷 读 取 、 插 入 、 删 
除 元 隶 ， 以 及 对 速度 敏感 的 场合 。 因 此 ， 散 列表 在 以 效率 、 性 能 著称 的 Nginx 服 务 器 中 得 到 
了 广泛 的 应 用 。 


注意 ，Nginx 不 只 提供 了 基本 的 散 列 表 。Nginx 作 为 一 个 web 服务器 ， 它 的 各 种 散 列 表 中 
的 关键 字 多 以 字符 串 为 主 ， 特 别 是 URI 域 名 ， 如 www.test.com 。 这 时 一 个 基本 的 要 求 就 出 现 
了 ， 如 何 让 散 列 表 支 持 通 配 符 呢 ?前 面 在 2.4.1 节 中 介绍 了 nginx.conf 中 主机 名 称 的 配置 ， 这 里 
的 主机 域名 是 允许 以 * 作 为 通配符 的 ， 包 括 前 置 通配符 ， 如 *.test.com， 或 者 后 置 通配符 ， 如 
www.test.*。 Nginx 封 站 了 ngx_hash_combined tt 容器， 专门 针 对 URI 域 名 支持 前 置 或 者 后 置 的 通 
配 符 〈 不 文 持 通配符 在 域名 的 中 间 ) 。 











本 节 会 以 一 个 完整 的 通配符 散 列 表 为 例 来 说 明 这 个 容 占 的 用 法 。 


7.7.1 ngx hash t 基 本 散 列 表 








散 列 表 是 根据 元 系 的 关键 码 值 而 直接 进行 访问 的 数据 结构 。 也 就 是 说 ， 它 通过 把 关键 码 
值 映 冉 到 表 中 一 个 位 置 来 访问 记录 ， 以 加 快 但 找 的 速度 。 这 个 映射 函数 人 d 作 散 列 方法 ， 存 
放 记 录 的 数组 叫做 散 列 表 。 


各 结构 中 存在 关键 字 和 K 相 等 的 记录 ， 则 必定 在 KK) 的 存储 位 置 上 。 由 此 ， 不 需要 比较 
便 可 直接 取得 所 得 记 录 。 我 们 称 这 个 对 应 关系 { 为 散 列 方法 ， 按 这 个 思想 建立 的 表 则 为 散 列 
表 。 





对 于 不 同 的 关键 字 ， 可 能 得 到 同一 散 列 地 址 ， 即 关键 码 keylzxtkey2， 而 Wkeyl)=Wkey2)， 
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这 种 现象 称 为 碰撞 。 对 该 散 列 方法 来 说 ， 有 具有 相同 函数 值 的 关键 字 称 作 同义词 。 综 上 上 所 述 ， 
根据 散 列 方法 H(key) 和 处 理 碰撞 的 方法 将 一 组 关键 字 映 象 到 一 个 有 限 的 连续 的 地 址 集 ( 区 
间 〉 上 ， 并 以 关键 字 在 地 址 集中 的 “ 象 ”作为 记录 在 表 中 的 存储 位 置 ， 这 种 表 便 称 为 散 列 表 ， 
这 一 映 象 过 程 称 为 散 列 造 表 或 散 列 ， 所 得 的 存储 位 置 称 为 散 列 地 址 。 


大 对 于 关键 字 集 合 中 的 任 一 个 关键 字 ， 经 散 列 方法 映 象 到 地 址 集合 中 任何 一 个 地 址 的 概 
率 古 相等 的 ， 则 称 此 类 散 列 方法 为 均匀 散 列 方法 ， 这 惑 使 关键 字 经 过 散 列 方法 得 到 了 一 
个 “随机 的 地 址 ”， 从 而 减少 了 碰撞 。 





1. 如 何 解 决 碰撞 问题 








如 果 得 知 散 列表 中 的 所 有 元 素 ， 那 么 可 以 设计 出 “完美 ”的 散 列 方法 ， 使 得 所 有 的 元 素 经 
过 fKR) 散 列 方法 运算 后 得 出 的 值 都 不 同 ， 这 样 就 避免 了 碰撞 问题 。 然 而 ， 通 用 的 散 列 表 是 不 
可 能 预知 散 列 表 中 的 所 有 元 聚 的 ， 这 样 ， 通 用 的 散 列 表 都 需要 解决 碰撞 问题 。 


当 散 列表 出 现 磁 撞 时 要 如 何 解决 呢 ? 一 般 有 两 个 简单 的 解决 方法 : 分 离 链接 法 和 开放 寻 
址 法 ， 


分 离 链 接 法 ， 束 是 把 散 列 到 同一 个 权 中 的 所 有 元 素 都 放 在 散 列表 外 的 一 个 链表 中 ， 这 样 
查询 元 系 时 ， 在 找到 这 个 槽 后 ， 还 得 过 有 历 链表 才能 找到 正确 的 元 素 ， 以 此 来 解决 碰撞 问题 。 








开放 寻 址 法 ， 即 毛 有 元 素 都 存放 在 散 列 表 中 ， 当 碍 找 一 个 元 系 时 ， 有 要 检查 规则 内 的 所 有 
的 表 项 《〈 例 如， 连续 的 非 空 槽 或 者 整个 空间 舟 符 合 散 列 方法 的 所 有 槽 )》， 直 到 找到 所 需 的 元 
素 ， 或 者 最 终 发 现 元素 不 在 表 中 。 开 放 寻 址 法 中 没有 链表 ， 也 没有 元 素 存 放 在 散 列 表 外 。 








Nginx 的 散 列 表 使 用 的 是 开放 寻 址 法 。 





开放 寻 址 法 有 许多 种 实现 方式 ，Nginx 使 用 的 是 连续 非 空 槽 存储 碰撞 元 象 的 方法 。 例 
如 ， 当 插入 一 个 元 系 时 ， 可 以 按照 散 列 方法 找到 指定 槽 ， 如 果 该 槽 非 空 且 其 存储 的 元 素 与 行 
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插入 元 素 并 非 同一 元 素 ， 则 依次 检查 其 后 连续 的 槽 ， 直 到 找到 一 个 空 槽 来 放置 这 个 元 素 为 
止 。 碍 询 元 素 时 也 是 使 用 类 似 的 方法 ， 即 从 散 列 方法 指定 的 位 置 起 检查 连续 的 非 空 槽 中 的 元 


2.ngx_hash t 散 列表 的 实现 


对 于 散 列 表 中 的 元 素 ，Nginx 使 用 ngx_hash elt t 结 构 体 来 存储 。 下 面 看 一 下 ngx hash elt t 
的 成 员 ， 代 码 如 下 。 





typedef struct 
/A 和 证 册 下 让 迪 兴 议 麻 二 加 搬 暂 灶 : 如 果 当 前 


ngx_hash elt 七 楷 为 空 ， 则 
value 的 值 为 


0 7 
value; 


void 
/* 元 素 关键 字 的 长 度 


u short 


len; 
// 元 素 关键 字 的 首 地 址 


u char name [1]; 
} ngx hash elt t; 





每 一 个 散 列 表 槽 都 由 1 个 ngx_hash_elt t 结 构 体 表示 ， 当 然 ， 这 个 槽 的 大 小 与 
ngx hash elt tf 结构 体 的 大 小 (也 就 是 sizeoftngx hash elt D) 是 不 相等 的 ， 这 是 因为 name 成 员 
只 用 于 指出 关键 字 的 首 地址 ， 而 关键 字 的 长 度 是 可 变 长 度 。 那 么 ， 一 个 槽 究竟 占用 多 大 的 空 
间 呢 ?其 实 这 是 在 初始 化 散 列 表 时 决定 的 。 基 本 的 散 列表 由 ngx_hash tt 结构 体 表示 ， 如 下 所 


小 。 











typedef struct 
// 指 ee 也 是 第 


1 个 槽 的 地 址 
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ngx hash elt 七 **buckets; 
// 散 列 表 中 楼 的 总 数 


ngx uint 七 size; 
} ngx hash t; 








因此 ， 在 分 配 puckets 成 员 时 惑 决 定 了 每 个 槽 的 长 度 《〈 限 制 了 每 个 元 素 关 键 字 的 最 大 长 
度 ) ， 以 及 整个 散 列 表 所 占用 的 空间 。 在 7.7.2 节 中 将 会 介绍 Nginx 提 供 的 散 列 表 初 始 化 方 
1 





如 图 7-10 所 示 ， 散 列表 的 每 个 槽 的 首 地 址 都 是 ngx_hash_elt t 结 构 体 ，value 成 员 指向 用 户 
意义 的 结构 体 ， 而 len 是 当前 这 个 模 中 name (也 就 是 元 素 的 关键 字 ) 的 有 效 长 度 。 
ngx_hash t 散 列表 的 buckets 指 各 了 散 列 表 的 起 始 地 址 ， 而 size 指 出 散 列 表 中 槽 的 总 数 。 


nex hash 1 
+ buckets 
上 S1Ze 


Fngx hash find () 





nex hash elt tt 


+ value 


+Hlen 
+-name 





用 户 结构 体 







value | len name value | len name ae len name 


共有 size 个 ngx hash_elt t 结构 体 


图 7-10 ngx_hash t 基 本 散 列 表 的 结构 示意 图 





ngx_hash t 散 列表 还 提供 了 ngx_hash find 方法 用 于 碍 询 元 素 ， 下 面 先 来 看 一 下 它 的 定义 。 





void ngx hash find(ngx hash t hash, ngx uint t key, u char *name, size t len) 
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其 中 ， 参 数 hash 是 散 列 表 结 构 体 的 指针 ， 而 key 则 是 根据 散 列 方法 算出 来 的 散 列 关键 字 ， 
name 和 1len 则 表示 实际 关键 字 的 地 址 与 长 度 。ngx hash find 的 执行 结果 就 是 返回 散 列 表 中 关键 
字 与 name、len 指 定 关键 字 完 全 相同 的 模 中 ，ngx hash_elt t 结 构 体 中 value 成 员 所 指向 的 用 户 
数据 。 如 果 ngx_hash find 没有 查询 到 这 个 元 素 ， 就 会 返回 NULL。 


3.ngx_hash t 的 散 列 方法 


Nginx 设 计 了 ngx_hash key_pt 散 列 方法 指针 ， 也 就 是 说 ， 完 全 可 以 按照 ngx hash key pt 的 
函数 原型 自 定义 散 列 方法 ， 如 下 所 示 。 





typedef ngx uint t (*ngx hash key pt) (u char *data, size t len); 








其 中 ， 传 入 的 data 是 元 素 关键 字 的 首 地 址 ， 而 len 是 元 素 关 键 字 的 长 度 。 可 以 把 任意 的 数 
据 结 构 强 制 转换 为 u char* 并 传 给 ngx hash key pt 散 列 方法 ， 从 而 决定 返回 什么 样 的 散 列 整 型 
关键 码 来 使 碰撞 率 降 低 。 


当然 ，Nginx 也 提供 了 两 种 基本 的 散 列 方法 ， 它 会 假定 关键 字 是 字符 串 。 如 果 关 键 字 确 
实 是 字符 串 ， 那 么 可 以 使 用 表 7-8 提 供 的 散 列 方法 。 


表 7-8 Nginx 提 供 的 两 种 散 列 方法 


散 列 方法 意 义 
ngx uint tngx hash key(u char *data, size_t len) 使 用 BKDR 算法 将 任意 长 度 的 字符 串 映 射 为 整 型 
3 将 字符 串 全 小 写 后 ， 再 使 用 BKDR 算法 将 任意 长 度 的 字 
ngx uint tngx hash key_ lc(u char *data. size tlen) |,,. es 
A 让 符 串 映射 为 整 型 





这 两 种 散 列 方法 的 区 别 仅仅 在 于 ngx hash key lc 将 关键 字 字 符 串 全 小 写 后 再 调用 
ngx_hash key 来 计算 关键 码 。 


7.7.2 ”支持 通配符 的 散 列 表 
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如 果 散 列表 元 素 的 关键 字 是 URI 域 名 ，Neginx 设 计 了 支持 简单 通配符 的 散 列 表 
ngx hash combined t， 那 么 它 可 以 支持 简单 的 前 置 通配符 或 者 后 置 通配符 。 


1. 原 理 





所 谓 支 持 通 配 符 的 散 列表 ， 就 是 把 基本 散 列 表 中 元 素 的 关键 字 ， 用 去 除 通 配 符 以 后 的 字 
符 作 为 关键 字 加 入 ， 原 理 其 实 很 简单 。 例 如 ， 对 于 关键 字 为 “www.test.*? 这 样 带 通配符 的 情 
况 ， 直 接 建立 一 个 专用 的 后 置 通配符 散 列 表 ， 存 储 元 素 的 关键 字 为 www.test。 这 样 ， 如 果 要 
检索 www.test.cn 是 否 匹 配 wwwi.test*， 可 用 Nginx 提 供 的 专用 方法 ngx_ hash find wc tail 检索， 
ngx_hash find_wc_tail 方 法 会 把 要 查询 的 www.test.cn 转 化 为 www.test 字 符 串 再 开始 查询 。 








同样 ， 对 于 关键 字 为 “.test.com "这样 带 前 置 通配符 的 情况 ， 也 直接 建立 了 一 个 专用 的 前 
置 通配符 散 列 表 ， 存 储 元 素 的 关键 字 为 com.test.。 如 果 我 们 要 检索 smtp.test.com 是 否 
配 .test.com， 可 用 Nginx 提 供 的 专用 方法 ngx hash find wc head 检 索 ，ngx hash find we head 
方法 会 把 要 查询 的 smtp.testcom 转 化 为 comtest. 字 符 串 再 开始 查询 〈 如 图 7-11 所 示 ) 。 





nex_hash _wlldcard 1 
+ hash : nex _hash 1 
+ value : char 


+ nex_hash _ find _wc _head () 





+nex_hash _find _wce _tall () 


图 7-11 ngx_hash_wildcard_t 基 本 通配符 散 列表 





Nginx 封 装 了 ngx_hash_ wildcard t 结 构 体 ， 专 用 于 表示 前 置 或 者 后 置 通配符 的 散 列 表 。 








typedef struct { 
// 基本 散 列 表 


ngx hash t hash; 
/* 当 使 用 这 个 


PPT TT TT “EE: // Ww | i NUuxor obe. con 





Value 指针 指向 用 户 数据 


4 
void value; 
} ngx hash wildcard t; 





实际 上 ，ngx_hash wildcard {只 是 对 ngx_hash {进行 了 简单 的 封装 ， 所 加 的 value 指 针 其 用 
途 也 是 多 样 化 的 。ngx_hash wildcard t 同 时 提供 了 两 种 方法 ， 分 别 用 于 查询 前 置 或 者 后 置 通 
配 符 的 元 素 ， 见 表 7-9。 





表 7-9 ngx_hash_wildcard_t 提 供 的 方法 


方法 而 人 












void *ngx hash find wc head hwc 是 散 列 表 的 指针 ，name | 将 待 查 询 关 键 字 name 转换 为 前 置 散 列 表 规 
(ngx_ hash wildcard t *hwre, 是 待 查 询 关 键 字 ，len 是 待 查 询 | 则 下 的 字符 串 再 递归 查询 ， 成 功 时 会 返回 找到 


u_char *name, size_t len) 关键 字 的 长 度 元 素 所 指向 的 用 户 数据 ， 否 则 返回 NULL 
void *ngx hash find wc tail hwc 是 散 列 表 的 指针 ，name| 将 待 查 询 关 键 字 name 转换 为 后 置 散 列表 规 
是 待 查询 关键 字 ，len 是 待 查询 | 则 下 的 字符 串 再 递归 查询 ， 成 功 时 会 返回 找到 
u char *name, size_t len) 关键 字 的 长 度 元 素 所 指 回 的 用 户 数据 ， 和 否则 返回 NULL 


(ngx hash wildcard t *hwec， 


下 面 回顾 一 下 Nginx 对 于 server name 主 机 名 通配符 的 支持 规则 。 
首先， 选择 所 有 字符 串 完 全 匹配 的 sefvet_hame， 如 www.testweb.com 。 
其次， 选择 通配符 在 前 面 的 setvet_hame， 如 #.testweb.com。 
. 再 次 ， 选 择 通 配 符 在 后 面 的 setvet_nhame， 如 wwwrtestweb.。 


实际 上 ， 上 面 介绍 的 这 个 规则 就 是 Nginx 实 现 的 ngx hash _ combined t 通 配 符 散 列表 的 规 
则 。 下 面 先 来 看 一 下 ngx hash combined t 的 结构 ， 代 码 如 下 。 





typedef struct { 
// 用 于 精确 匹配 的 基本 散 列 表 


ngx hash t hash; 
// 用 于 查询 前 置 通配符 的 散 列 表 
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ngx hash wildcard t *wc head; 


// 用 于 查询 后 置 通配符 的 散 列 表 


ngx hash wildcard t *xwC tail; 
} ngx hash combined t; 





如 图 7-12 所 示 ，ngx_hash_combined t 是 由 3 个 散 列 表 所 组 成 : 第 1 个 散 列 表 hash 是 普通 的 
基本 散 列 表 ， 第 2 个 散 列 表 wc_head 所 包含 的 都 是 带 前 置 通 配 符 的 元 素 ， 第 3 个 散 列 表 wce_tail 
所 包含 的 都 是 带 后 置 通配符 的 元 素 。 
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ngx_hash _combined _+ 


+hash : ngx_hash t 





| + wc_head : ngx_hash_wildcard _+ 
人 + wc tail : ngx_hash_wildcard _t 
/4 +ngx_hash_find _combined () 


ED EE 


www .test.com x 


应 的 结构 体 





完全 匹配 的 散 列 表 


前 PT 
i 


ngx_hash _elt _+ 





前 置 通配符 散 列 表 


www .test.* 对 /MF 
We | 


后 管 通配符 散 列 表 


图 7-12 ”ngx_hash_combined_t 通 配 符 散 列表 的 结构 示意 图 


@@ 注音 ”前 置 通配符 散 列 表 中 元 素 的 关键 字 ， 在 把 + 通配符 去 挤 后 ， 会 按照 “” 竺 号 
分 隔 ， 并 以 倒序 的 方式 作为 关键 字 来 存储 元 素 。 相 应 的 ， 在 查询 元 素 时 也 是 做 相同 处 理 。 


在 查询 元 素 时 ， 可 以 使 用 ngx hash combined t 提 供 的 方法 ngx hash find combined， 下 面 
先 来 看 看 它 的 定义 〈 它 的 参数 、 返 回 值 含义 与 ngx_hash find wc_head 或 者 
ngx hash find wc tail 方 法 相同 ) 。 








void ngx hash find combined(ngx hash combined t hash, ngx uint t key, u char *name,size t len); 








在 实际 向 ngx_hash_combined t 通 配 符 散 列表 查询 元 素 时 ，ngx_hash find_combined 方 法 的 
活动 图 如 图 7-13 所 示 ， 这 是 有 严格 顺序 的 ， 即 当 1 个 查询 关键 字 同 时 匹配 3 个 散 列 表 时 ， 一 定 
是 返回 普通 的 完全 匹配 散 列 表 的 相应 元 素 。 
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在 hash 完 全 匹配 散 列 表 中 查询 元 素 





» 


[没有 查询 到 |] 


在 wc_head 通 配 符 前 置 散 列 表 中 查询 元 素 





[没有 查询 到 | [已 经 查询 到 ] 





在 wctail 通配符 后 置 散 列 表 中 查询 元 条 
[已 经 查询 到 | 





[未 查询 到 , 返回 NULL] [已 经 查询 到 ] 
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图 7-13 ”通配符 散 列 表 ngx_hash_find_combined 方 法 查询 元 素 的 活动 图 


2. 如 何 初始 化 


上 文中 对 于 普通 的 散 列 表 和 通配符 散 列 表 的 原理 和 查询 方法 做 了 详细 的 解释 ， 实 际 上 ， 
Nginx 也 封装 了 完善 的 初始 化 方法 ， 以 用 于 这 些 散 列表 ， 并 且 Nginx 还 具备 在 初始 化 时 放 加 通 


配 符 元 素 的 能 


初始 化 方法 的 使 用 。 


。 鉴 于 此 ， 如 果 功 能 较 多 ， 初 始 化 方法 的 使 用 就 会 有 些 复 杂 。 下 面 介绍 一 下 


Nginx 专 门 提供 了 ngx_hash_init_ 结构 体 用 于 初始 化 散 列 表 ， 代 码 如 下 。 





typedef struct { 


3 不 4 


// 指向 普通 的 完全 匹配 散 列表 


ngx hash 七 *hash; 


// 用 于 初始 化 预 添加 元 素 的 散 列 方法 


ngx hash key pt key; 
// 散 列 表 中 楷 的 最 大 数目 


ngx uint t max size; 


// 散 列 表 中 一 个 槽 的 空间 大 小 ， 


ngx uint t bucket size; 


// 散 列 表 的 名 称 


char name; 


/内 存 池 ， 它 分 配 艇 列表 (最 多 


包括 


1 个 普通 散 列表 、 


1 个 前 置 通配符 散 列 表 、 


1 个 后 置 通配符 散 列 表 ) 中 的 所 有 模 


/ 


ngx pool t pool; 


它 限 制 了 每 个 散 列表 元 素 关键 字 的 最 大 长 度 


/* 临 时 内 存 池 ， 它 仅 存 在 于 初始 化 散 列 表 之 前 。 它 主要 用 于 分 配 一 些 临 时 的 动态 数组 ， 带 通配符 的 元 素 在 初始 化 时 需要 用 到 这 些 数 组 
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4 
ngx pool t temp pool; 
} ngx hash init t; 





ngx_hash_init t 结 构 体 的 用 途 只 在 于 初始 化 散 列表 ， 到 底 初 始 化 散 列 表 时 会 预 分 配 多 少 个 
模 呢 ? 这 并 不 完全 由 max size 成 员 决 定 的， 而 是 由 在 做 初始 化 准备 时 预先 加 入 到 散 列 表 的 所 
有 元 素 决 定 的 ， 包 插 这 些 元 素 的 总 数 、 每 个 元 素 关 键 字 的 长 度 等 ， 还 包括 操作 系统 一 个 页 面 
的 大 小 。 这 个 算法 较 复杂 ， 可 以 在 ngx hash init t 函 数 中 得 到 。 我 们 在 使 用 它 时 只 需要 了 解 在 
初始 化 后 每 个 ngx_hash t 结 构 体 中 的 size 成 员 不 由 ngx_hash init tt 完全 决定 即 可 。 图 7-14 显 示 了 
ngx_hash init t 结 构 体 及 其 支持 的 方法 。 


nex hash init t 
Fhash 
| key 
tmax size 
tbucket size 
tname 
+ pool 
ttemp pool 


tngx hash init () 


Fngx hash wildcard init () 





图 7-14 ”ngx_hash_init_t 的 结构 及 其 提供 的 方法 


ngx hash init t 的 这 两 个 方法 负责 将 ngx hash keys arrays t 中 的 相应 元 素 初 始 化 到 散 列 表 
中 ， 表 7-10 描 述 了 这 两 个 初始 化 方法 的 用 法 。 


表 7-10 ”ngx_hash_init_t 提 供 的 两 个 初始 化 方法 


方法 名 






hinit 是 散 列 表 初 始 化 结构 体 的 指针 ;| 初始 化 基本 的 散 列 表 。 返 回 


ngx int tnex hash init tA ge es RE 
SR names 是 数组 的 首 地 址 ， 这 个 数组 中 每 个 元 |NGX_OK， 表 示 初 始 化 成 功 ， 这 


(ngx hash init t *hinit, 


ngx hash key t *names, ee ea eh 
es 预 添加 到 散 列 表 中 的 元 素 ; nelts 是 names 数 | >hash 散 列 表 中 了 ; 返回 NGX 


组 的 元 素数 日 ERROR ， 表 示 初 始 化 失败 


上 NEN TDHD tp: / /WWW Tinuxprobe. con 


ngx uint tnelts) 





方法 名 


ngx int tngx hash wildcard init 
(ngx hash init t *hinit, 
ngx hash key t *names, 


ngx uint tnelts) 





执行 意义 

hinit 是 散 列 表 初 始 化 结构 体 的 指针 ;| 初始 化 通配符 散 列 表 (前 
names 是 数组 的 首 地 址 ， 这 个 数组 中 每 个 元 | 置 或 者 后 置 )。 返 回 NGX_ 
素 以 ngx_hash_key_t 作为 结构 体 ， 它 存储 着 |OK， 表 示 初 始 化 成 功 ， 这 时 
预 添加 到 散 列 表 中 的 元 素 (这 些 元 素 的 关键 |names 数组 已 经 添加 到 hinit- 
字 要 么 含有 前 置 通 配 符 ， 要 么 含有 后 置 通 配 | >hash 散 列 表 中 了 ; 返回 NGX_ 
符 ); nelts 是 names 数组 的 元 素数 日 ERROR ， 表 示 初 始 化 失败 





表 7-10 的 两 个 方法 都 用 到 了 ngx hash key t 结 构 ， 下 面 简 单 地 介绍 一 下 它 的 成 员 。 实 际 
上 ， 如 果 只 是 使 用 散 列 表 ， 完 全 可 以 不 用 关心 ngx hash key t 的 结构 ， 但 为 了 更 深入 地 理解 


和 应 用 还 是 简要 介绍 一 下 它 。 





typedef struct { 
// 元 素 关键 字 


ngx str t key; 


// 由 散 列 方法 算出 来 的 关键 码 


ngx uint t key hash; 
// 指向 实际 的 用 户 数 据 


void *value; 
} ngx hash key t; 





ngx hash keys arrays t 对 应 的 ngx hash add key 方法 负责 构造 ngx hash key t 结 构 。 下 面 来 
看 一 下 ngx_hash_keys_arrays_t 结 构 体 ， 它 不 负 员 构造 散 列 表 ， 然 而 它 却 是 使 用 ngx_hash_init 或 
者 ngx hash wildcard init 方 法 的 前 提 条 件 ， 换 句 话 说 ， 如 果 先 构造 好 了 ngx hash keys_arrays_t 
结构 体 ， 就 可 以 非常 简单 地 调用 ngx hash init 或 者 ngx hash wildcard init 方 法 来 创建 支持 通 配 


符 的 散 列 表 了 。 





typedef struct { 
/* 下 面 的 


keys_hash.、 


dns wc head hash、 


ans 中 aE nfsb 本 Bk 于, FL 站 http:// Ww | 1 nNuUxorobe. con 





hsize 指 明了 散 列 表 的 槽 个 数 ， 其 简易 散 列 方法 也 需要 对 


hsize 求 余 


ngx uint t hsize; 


内 存 池 ， 用 于 分 配 永久 性 内 存 ， 到 目前 的 


Nginx 版 本 为 止 ， 该 


pool 成 员 没 有 任何 意义 


ngx pool t pool; 
// 临时 内 存 池 ， 下 面 的 动态 数组 需要 的 内 存 都 由 


temp Pool 内 存 池 分 配 


ngx Pool 七 *temp pool; 
// 用 动态 数组 以 


ngx_hash_key 结构 体 保存 着 不 含有 通配符 关键 字 的 元 素 


ngx array t keys; 


/* 一 个 极其 简易 的 散 列 表 ， 它 以 数组 的 形式 保存 着 


hsize 个 元 素 ， 每 个 元 素 都 是 


ngx_array_t 动 态 数 组 。 在 用 户 添加 的 元 素 过 程 中 ， 会 根据 关键 码 将 用 户 的 


ngx _str 七 类 型 的 关键 字 添 加 到 


ngx_array tt 动态 数组 中 。 这 里 所 有 的 用 户 元 素 的 关键 字 都 不 可 以 带 通配符 ， 表 示 精 确 匹 配 


ngx array t keys hash; 
/* 用 动态 数组 以 





ngx_hash key_t 结 构 体 保 存 着 含有 前 置 通 配 符 关键 字 的 元 素 生成 的 中 间 关 键 字 


ngx array t dns wc head; 


一 个 极其 简易 的 散 列表 ， 它 以 数组 的 形式 保存 着 





hsize 个 元 素 ， 每 个 元 素 都 是 
ngx_array tt 动态 数组 。 在 用 户 添加 元 素 过 程 中 ， 会 根据 关键 码 将 用 户 的 


ngx _str 七 类 型 的 关键 字 添加 到 


TiNNNiNnnn http://wWwWw linuxorobe.con 





ngx_array 七 动态 数组 中 。 这 里 所 有 的 用 户 元 素 的 关键 字 都 带 前 置 通 配 符 


ngx array t dns wc head hash; 


/* 用 动态 数组 以 





ngx_hash key 七 结构 体 保 存 着 含有 后 置 通配符 关键 字 的 元 素 生成 的 中 间 关 键 字 


ngx array t dns wc tail; 


一 个 极其 简易 的 散 列 表 ， 它 以 数组 的 形式 保存 着 





hsize 个 元 素 ， 每 个 元 素 都 是 


ngx_array tt 动态 数组 。 在 用 户 添加 元 素 过 程 中 ， 会 根据 关键 码 将 用 户 的 


ngx _str 七 类 型 的 关键 字 添加 到 


ngx_ array tt 动态 数组 中 。 这 里 所 有 的 用 户 元 素 的 关键 字 都 带 后 置 通 配 符 


/ 
ngx array t dns wc tail hash; 
} ngx hash keys arrays t; 











如 图 7-15 所 示 ，ngx_hash_keys_arrays_t 中 的 3 个 动态 数组 容器 keys、dns_wc_head、 
dns_wc_tail 会 以 ngx_hash key t 绪 构 体 作为 元 素 类 型 ， 分 别 保存 完全 匹配 关键 字 、 矶 前 置 通 配 
符 的 关键 字 、 带 后 置 通配符 的 关键 字 。 同 时 ，ngx_hash keys_arrays t 建 立 了 3 个 简易 的 散 列 表 
keys hash、dns wc head hash、dns wc tail hash， 这 3 个 散 列 表 用 于 快速 向 上 述 3 个 动态 数组 
容器 中 插入 元 素 。 
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ngx hash key t ngx hash keys arrays _t 


+key 
十 key_hash 
+value 





dns _we head _hash 


+dns we tail 
+dns wc tail hash 
/A pi +ngx hash keys array _init () 


砚 J +ngx hash add key() 












www .test.com 关键 入 





ngx_str t 组 成 的 动态 数组 


| 
ngx_str t 组 成 的 动态 数组 


在 上 面 3 个 散 列 表 中 ， 按 
照 每 个 关键 字 的 散 列 码 指 
定 的 槽 存放 ngx_str_t 组 成 
的 动态 数组 ， 每 个 ngx_str_1 
指向 真正 的 关键 字 的 值 







*#, test .com 关键 字 





ngx str_ t 组 成 的 动态 数组 


www .test.* 关键 字 - 


在 这 3 个 动态 数组 的 
ngx hash key t 元 素 中 ， 
key 指 问 关 键 字 的 值 ， 
key_hash 是 计算 出 的 散 列 
码 ，value 指 向 实际 的 用 
ngx hash key t 户 数据 


图 7-15 ”ngx_hash_keys_atfays_t 中 动态 数组 、 散 列表 成 员 的 简易 示意 图 


为 什么 要 设立 这 3 个 简易 散 列 表 呢 ? 如 有 果 没 有 这 3 个 散 列 表 ， 在 同 keys、dns_wc_head、 
dns_wc_tail 动 态 数组 添加 元 素 时 ， 为 了 避免 出 现 相同 关键 字 的 元 素 ， 每 添加 一 个 关键 字 元 素 
都 需要 遍历 整个 数组 。 有 了 keys hash、dns wc head hash、dns wc tail hash 这 3 个 简易 散 列 
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表 后 ， 每 向 keys、dns_wc_head、dns_wc tail 动 态 数组 添加 1 个 元 素 时 ， 就 用 这 个 元 素 的 关键 
字 计 算出 散 列 码 ， 然 后 按照 散 列 码 在 keys_ hash、dns wc head hash、dns wc tail hash 散 列表 
中 的 相应 位 置 建立 ngx_array 动态 数组 ， 动 态 数 组 中 的 每 个 元 素 是 ngx_str t， 它 指向 关键 字 

字符 串 。 这 样 ， 再 次 添加 同名 关键 字 时 ， 就 可 以 由 散 列 码 立 刻 获得 曾经 添加 的 关键 字 ， 以 此 
来 判定 是 否 合法 或 者 进行 元 素 合并 操作 。 








ngx_hash keys_arrays t 之 所 以 设计 得 比较 复杂 ， 是 为 了 让 keys、dns_wce_head、 
dns_wc_tail 这 3 个 动态 数组 中 存放 的 都 是 有 效 的 元 素 。 表 7-11 介 绍 了 ngx_hash keys_arrays tt 提 
供 的 两 个 方法 。 


表 7-11 ngx_hash_keys_atfays_t 提 供 的 两 个 方法 


二 EX 
ha 是 要 初始 化 的 ngx_hash keys_arrays t| 初始 化 ngx hash keys arrays { 
ngx int tngx hash keys_array _ init | 结构 体 指 针 ; type 取 值 范围 有 两 个 ， 其 中 | 结构 体 ， 在 回 ha 加 入 成 员 前 必 
(ngx hash keys arrays t *ha, NGX _ HASH SMALL 表示 待 初始 化 的 元 | 须 先 调 用 该 方法 。 返 回 NGX_ 
ngx_uint t type) 素 较 少 ， 而 NGX_HASH LARGE 表示 待 |OK， 表 示 成 功 ， 返 回 NGX_ 
初始 化 的 元 素 较 多 ERROR， 表 示 失 败 








ha 是 要 初始 化 的 ngx_hash keys_arrays 


t 结 构 体 指针 ; key 是 添加 元 素 的 关键 字 ; 





value 是 key 关键 字 对 应 的 用 户 数据 的 指 





ngx int tngx hash add key 针 ; flags 的 取 值 有 3 种 : NGX HASH _ : a i 
ee 问 ha 中 添加 1 个 元 素 。 返 
(ngx_ hash keys arrays_t *ha, WILDCARD KEY 表示 需要 处 理 通 配 符 ; We 
be | NGXHOK; 表示 成 功 ; 返回 
ngx str t *key. Vold *value， NGX HASH READONLY KEY 表示 关键 NGX ERROR， 表 示 失 败 
ES i 二 二 SR z 9 小 大 凡 
ngx uint t flags) 字 不 可 以 做 更 改 (也 就 是 不 可 以 通过 全 小 站 


写 关 键 字 来 获取 散 列 码 ); 其 他 值 表 示 既 不 
处 理 通配符 ， 又 允许 通过 把 关键 字 全 小 写 
来 获取 散 列 码 





ngx_hash keys_array_init 方 法 的 type 参 数 将 会 决定 ngx_hash keys_arrays_t 中 3 个 简易 散 列 表 
的 大 小 。 当 tfype 为 NGX HASH SMALL 时 ， 这 3 个 散 列 表 中 槽 的 数目 为 107 个 ， 当 type 为 
NGX HASH LARGE 时 ， 这 3 个 散 列 表 中 槽 的 数目 为 10007 个 。 


在 使 用 ngx hash keys_array_init 初 始 化 ngx_hash keys_arrays_t 结 构 体 后 ， 就 可 以 调用 


Te 





供 的 两 个 初始 化 方法 来 创建 散 列 表 ， 这 样 得 到 的 散 列 表 就 是 完全 可 用 的 容器 了 。 


7.7.3” 带 通配符 散 列 表 的 使 用 例子 


散 列 表 元 素 ngx hash elt t 中 value 指 针 指 向 的 数据 结构 为 下 面 定 义 的 TestWildcardHash- 
Node 结 构 体 ， 代 码 如 下 。 





typedef struct { 
// 用 于 散 列 表 中 的 关键 字 


ngx str t servername; 


// 这 个 成 员 仅 是 为 了 方便 区 别 而 已 


ngx int t seqg; 
} TestWildcardHashNode; 





每 个 散 列 表 元 素 的 关键 字 是 servername 字 符 串 。 下 面 先 定义 ngx_hash init t 利 
ngx_hash keys_arrays_t 变 量 ， 为 初始 化 散 列 表 做 准备 ， 代 码 如 下 。 





// 定义 用 于 初始 化 散 列 表 的 结构 体 


ngx hash _ init 七 hash; 
/* ngx hash keys arrays 苇 用 于 预先 向 散 列 表 中 添加 元 素 ， 这 里 的 元 素 支持 带 通配符 





4 
ngx hash keys arrays 七 ha; 


// 支持 通配符 的 散 列表 





ngx hash combinedq t combinedHash; 
ngx memzero(&ha, sizeof (ngx hash keys arrays 七 ) ) ; 











combinedHash 是 我 们 定义 的 用 于 指 辣 散 列 表 的 变量 ， 它 包括 指向 3 个 散 列 表 的 指针 ， 下 
面 会 依次 给 这 3 个 散 列 表 指 针 赋 值 。 





// 临时 内 存 池 只 是 用 于 初始 化 通配符 散 列表 ， 在 初始 化 完成 后 就 可 以 销毁 掉 
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return NGX ERROR; 





} 
/* 由 于 这 个 例子 是 在 


ngx http mytest postconf 函 数 中 的 ， 所 以 就 用 了 


ngx Conf 七 类 型 的 


cf 下 的 内 存 池 作为 散 列 表 的 内 存 池 


ha.pool = cf->pool; 





调用 ngx hash keys array init 方 法 来 初始 化 nha， 为 下 一 步 同 ha 中 加 入 散 列 表 元 素 做 好 准 
备 ， 代 码 如 下 。 








If (ngx hash keys array init (gha, NGX HASH LARGE) != NGX OK) { 
return NGX ERROR; 








} 








本 节 按 照 图 7-12 和 图 7-15 中 的 例子 建立 3 个 数据 ， 并 且 会 敢 善 7.7 节 中 介绍 的 散 列 表 内 
容 。 我 们 建立 的 testHashNode[3] 这 3 个 TestWildcardHashNode 类 型 的 结构 体 ， 分 别 表示 可 以 用 
前 置 通配符 匹配 的 散 列 表 元 素 、 可 以 用 后 置 通 配 符 匹 配 的 散 列 表 元 素 、 需 要 完全 匹配 的 散 列 
表 元 订 。 














TestWildcardHashNode testHashNode[3]; 

testHashNode[0] .servername.len = ngx strlen(".test.com"); 
testHashNode[0].servername.data = ngx pcalloc (cf->pool, ngx strlen(".test.com")); 

ngx memcpy (testHashNode[0].servername.data,".test.com",ngx strlen(".test.com")); 
testHashNoqe [1] .servername.len = ngx strlen ("www.test.*"); 

testHashNoqdqe [1] .servername.data = ngx pcalloc(cf->pool, ngx strlen("www.test.*")); 

ngx memcpy (testHashNoqe [1] .servername.data,"www.test.*",ngx strlen("www.test.*")); 
testHashNode[2] .servername.len = ngx strlen ("www.test.com"); 

testHashNode[2] .servername.data = ngx pcalloc (cf->pool, ngx strlen("www.test.com")); 
ngx memcpy (testHashNode [2] .servername.data,"www.test.com",ngx strlen ("www.test.com")); 



























































下 面 通过 调用 ngx hash add key 方 法 将 testHashNode[3] 这 3 个 成 员 添 加 到 ha 中 。 





for (i = 0; i < 3; i++) 


testHashNode[il].seq = i; 
ngx hash add key(&ha, &testHashNodel[il].servername, 
&testHashNode[il] NGX HASH WILDCARD KEY); 
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注意 ， 在 上 面 添加 散 列 表 元 素 时 ，flag 设 置 为 NGX_HASH WILDCARD _ KEY， 这 样 才 会 
处 理 带 通配符 的 关键 字 。 


在 调用 ngx hash init t 的 初始 化 函数 前 ， 先 得 设置 好 ngx hash init t 中 的 成 员 ， 如 槽 的 大 
小 、 艇 列 方法 等 ， 如 下 有 所 示 。 





hash.key = ngx hash key lc; 

hash.max size = 100; 

hash.bucket size = 48; 

hash.name = "test server name hash"; 
hash.pool = cf->pool; 











ha 的 keys 动 态 数组 中 存放 的 是 需要 完全 匹配 的 关键 字 ， 如 果 keys 数 组 不 为 空 ， 那 么 开始 
初始 化 第 1 个 散 列 表 ， 代 码 如 下 。 





if (ha.keys.nelts) { 
/* 需 要 显 式 地 把 


ngx hash init 七 中 的 


hash 指 针 指 向 


combinedHash 中 的 完全 匹配 艇 列表 


*/ 
hash.hash = &combinedHash.hash; 
// 初始 化 完全 匹配 散 列 表 时 不 会 使 用 到 临时 内 存 池 
hash.temp Pool = NULL; 
/* 将 
keys 动 态 数组 直接 传 给 


ngx hash init 方法 即 可 ， 


ngx _ hash :init 七 中 的 


hash 指 针 就 是 初始 化 成 功 的 散 列 表 


* 
if (ngx hash init(&hash, ha.keys.elts, ha.keys.nelts) != NGX OK) 
{ 
return NGX ERROR; 





} 
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下 面 继续 初始 化 前 置 通配符 散 列 表 ， 人 代码 如 下 。 





if (ha.dns wc head.nelts) { 
hash.hash = NULL; 
// 注意 ， 


ngx hash wildcard init 方 法 需要 使 用 临时 内 存 池 


hash.temp pool = ha.temp pool; 
if (ngx hash wildcard init(&hash, ha.dns wc head.elts, 
ha.dns wc head.nelts) != NGX OK) 
{ 
return NGX ERROR; 
} 
/* ngx hash init 七 中 的 





hash 指 针 是 


ngx_hash wildcard init 初始 化 成 功 的 散 列 表 ， 需 要 将 它 赋 到 


combinedHash.wc_head 前 置 通配符 散 列 表 指针 中 


combinedHash.wc head = (ngx hash wildcard t ) hash.hash; 





下 面 继续 初始 化 后 置 通配符 散 列 表 ， 代 码 如 下 。 





if (ha.dns wc tail.nelts) { 
hash.hash = NULL; 
// 注意 ， 


ngx hash wildcard init 方 法 需要 使 用 临时 内 存 池 


hash.temp pool = ha.temp pool; 
if (ngx hash wildcard init(&hash, ha.dns wc tail.elts, 
ha.dns wc tail.nelts)!= NGX OK) 
return NGX ERROR; 


} 
/* ngx hash init 七 中 的 


hash 指 针 是 


ngx_hash wildcard init 初 始 化 成 功 的 散 列 表 ， 需 要 将 它 赋 到 


combinedHash.wc tail 后 置 通配符 散 列 表 指 针 中 


combinedHash.wc tail = (ngx hash wildcard t ) hash.hash; 








到 此 ， 临 时 内 存 池 已 经 没有 存在 的 意义 了 ， 也 就 是 说 ，ngx_hash_keys_arrays_t 中 的 这 些 
数组 、 简 易 散 列表 都 可 以 销毁 了 。 这 时 ， 只 需要 简单 地 把 temp_ pool 内存 池 销毁 就 可 以 了 ， 
代码 如 下 。 





ngx destroy pool (ha.temp Pool) ， 








下 面 检 查 一 下 散 列 表 是 否 工 作 正 常 。 自 先 ， 人 查询 关键 字 www.test.org， 实 际 上 ， 它 应 该 
匹配 后 置 通配符 散 列 表 中 的 元 素 www.test*， 人 代码 如 下 。 








// 首先 定义 待 查询 的 关键 字 字 符 串 


findServer 
ngx str t findServer; 
findServer.len = ngx _ strlen ("www.test.org" 


/* 为 件 站 把 负 家 在册 兰 池 市 分 配 空间 以 保存 关键 字 呢 ? 和 


ngx _ hash key lc， 它 会 试 着 把 关键 字 全 小 写 


findServer.data = ngx pcalloc (cf->pool, ngx strlen ("www.test.org")); 
ngx memcpy (findServer.data, "www.test.org",ngx strlen ("www.test.org")); 
ngx hash find combined 方 法 会 查找 出 


Www .test.* 对 应 的 散 列 表 元 素 ， 返 回 其 指向 的 用 户 数 据 


ngx hash find combined， 也 就 是 


testHashNode[1]*/ 
TestWildcardHashNode* findHashNode = 
ngx hash find combined (&combinedHash, 
ngx hash key lc (findServer.data, findServer.len), 
findServer.data, findServer.len); 





如 果 没 有 查询 到 的 话 ， 那 么 findHashNode 值 为 NULL 空 指针 。 


下 面试 着 查询 www.test.com， 实 际 上 ，testHashNode[0]、testHashNode[1]、 
testHashNode[2] 这 3 个 节点 都 是 匹配 的 ， 因 为 *.test.com、www.test.*、wwwi.test.com 明 显 都 是 
匹配 的 。 但 按照 完全 匹配 最 优先 的 规则 ，ngx hash find combined 方 法 会 返回 testHashNode[2] 
的 地 址 ， 也 就 是 www.testcom 对 应 的 元 素 。 
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findServer.len = ngx Strlen("www.test.com'" ) ， 
findServer.data = ngx pcalloc(cf->pool, ngx Strlen("www.test .com'" ) ) ， 
ngx memcpy (findServer.data, "www.test.com",ngx strlen ("www.test.com")); 
findHashNode = ngx hash find combined(&combinedHash, 
ngx hash key lc (findServer.data, findServer.len), 
findServer.data, findServer.len); 





下 面 测试 一 下 后 置 通配符 散 列 表 。 如 果 查 询 的 关键 字 是 “smtp.test.com”， 那 么 查询 到 的 
应 该 是 关键 字 为 *.test.com 的 元 素 testHashNode[0]。 





findServer.len = ngx strlen("smtp.test.com"); 
findServer.data = ngx pcalloc(cf->pool, ngx strlenl("smtp.test.com")); 
ngx memcpy (findServer.data,"smtp.test.com",ngx strlen("smtp.test.com")); 
findHashNode = ngx hash find combined(&combinedHash, 
ngx hash key lc (findServer.data, findServer.len), 
findServer.data, findServer.len); 
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7.8 小结 


本 章 介 绍 了 Nginx 的 利用 容 希 ， 这 对 我 们 开发 复杂 的 Nginx 模 块 非常 有 意义 。 当 我 们 需要 
用 到 高 级 的 数据 结构 时 ， 选 择 手 段 是 非常 少 的 ， 因 为 makefile 都 是 由 Nginx 的 configure 脚 本 生 
成 的 ， 如 果 想 加 入 第 三 方 中 间 件 将 会 种 来 许多 风险 ， 而 目 己 重新 实现 容 占 的 代价 又 非 第 高 ， 
这 时 使 用 Nginx 提 供 的 通用 容器 就 很 有 意义 了 。 然 而 ，Nginx 封 装 的 这 几 种 容器 在 使 用 上 各 不 
相同 ， 有 些 令 人 头疼 ， 而 且 代 码 注释 几乎 没有 ， 束 造成 了 使 用 这 几 个 容 圳 很 困难 ， 还 容易 出 
错 。 通 过 阅读 本 章 内 容 ， 相 信 读 者 不 再 会 为 这 些 容 器 的 使 用 而 烦恼 了 ， 而 且 也 应 该 具备 轻松 
修改 、 升 级 这 些 容 器 的 能 力 了 。 了 解 本 章 介 绍 的 容器 是 今后 深入 开 及 Nginx 的 基础 。 
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下 viz 


第 三 部 分 深入 Nginx 
` 第 8 章 ”Nginx 基 础 架构 
` 第 9 章 ”事件 模块 
` 第 10 章 HTTP 框架 的 初始 化 
` 第 11 章 HTIP 框 架 的 执行 流程 
` 第 12 章 upstream 机 制 的 设计 与 实现 
` 第 13 章 ”邮件 代理 模块 
` 第 14 章 ”进程 间 的 通信 机 制 


` 第 16 章 slab 共享 内 存 
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第 8 革 ”Nginx 基 础 架构 


在 本 书 的 第 二 部 分 ， 我 们 已 经 学 习 了 如 何 开发 HTTP 模块 ， 这 使 得 我 们 可 以 实现 高 性 
能 、 定 制 化 的 Web 服 务 器 功能。 不 过 ，Nginx 目 身 是 高 度 模块 化 设计 的 ， 它 给 予 了 每 一 个 基本 
的 Nginx 模 块 足够 的 灵活 性 ， 也 就 是 说 ， 我 们 不 仅仅 能 开发 HTTP 模 其 ， 还 可 以 方便 地 开发 任 
何 基于 TCP 的 模块 ， 甚 至 可 以 定义 一 类 新 的 Nginx 模 块 ， 就 像 HTTP 模 块 、mail 模 块 曾经 做 过 
的 那样 。 任 何 我 们 能 想到 的 功能 ， 只 要 符合 本 章 中 描述 的 Nginx 设 计 原 则 ， 都 可 以 以 模块 的 
方式 添加 到 Nginx 服 务 中 ， 从 而 提供 强大 的 Web 服 务 器 。 











另外 ，Nginx 的 BSD 许 可 证 足够 开放 和 自由 ， 因 此 ， 当 Nginx 的 一 些 通 用 功能 与 要 求 不 符 
合 我 们 的 想象 时 ， 还 可 以 尝试 着 直接 更 改 它 的 官方 代码 ， 从 而 更 直接 地 达到 业务 要 求 。 同 
时 ，Nginx 也 处 于 快速 的 发 展 中 ， 代 码 中 免不了 会 有 一 些 Bug， 如 果 我 们 对 Nginx 的 架构 有 充 
分 的 了 解 ， 也 可 以 积极 地 协助 完善 Nginx 框 架 代 码 。 





以 上 这 些 方向 ， 都 需要 我 们 在 整体 上 对 Nginx 的 架构 有 清晰 的 认识 。 因 此 ， 本 章 的 写作 
目的 只 有 两 个 : 
对 Nginx 的 设计 思路 做 一 个 概括 性 的 说 明 ， 帮 助 读者 了 解 Nginx 的 设计 原则 〈 见 8.1 节 和 
8.2 节 ) 。 
` 将 从 有 具体 的 框架 代码 入 手 ， 讨 论 Nginx 如 何 启动 、 运 行 和 退出 ， 这 里 会 涉及 具体 实现 
细节 ， 如 mastet 进 程 如 何 管理 wotket 进 程 、 每 个 模块 是 如 何 加 载 到 进程 中 的 等 ( 见 8.3 节 ~8.6 
和 
通过 阅读 本 章 内 容 ， 我 们 将 会 对 Nginx 这 个 Web 服 务 器 有 一 个 全 面 的 认识 ， 并 对 日 益 增 长 
的 各 种 Nginx 模 块 与 核心 模块 的 关系 有 一 个 大 概 的 了 解 。 另 外 ， 本 章 内 容 将 为 下 一 章 〈 事 件 


模块 》 以 及 后 续 章节 中 HTTP 模 块 的 学 习 打下 基础 。 
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8.1 ”Web 服务 器 设计 中 的 关键 约束 


Nginx 是 一 个 功能 堪 比 Apache 的 Web 服 务 占 。 然 而 ， 在 设计 时 ， 为 了 使 其 能 够 适应 互联 网 
用 户 的 蜗 速 增长 及 其 带 来 的 多 样 化 需求 ， 在 基本 的 功能 需求 之 外 ， 还 有 许多 设计 约束 。 
Nginx 作 为 Web 服 务 器 受制 于 Web 传 输 协议 目 身 的 约束 ， 另 外 ， 下 面 将 说 明 的 7 个 关注 点 也 是 
Nginx 架 构 设 计 中 的 关键 约束 ， 本 革 会 分 节 人 简要 介绍 这 些 概念 。 在 8.2 市 中 ， 我 们 将 带 着 这 些 


问题 再 看 一 下 Nginx 是 如 何 有 效 提升 这 些 关 注 扣 属性 的 。 


1. 性 能 





性 能 是 Nginx 的 根本 ， 如 果 性 能 无 法 超越 Apache， 那 么 它 也 就 没有 存在 的 意义 了 。 这 里 
所 说 的 性 能 主体 是 web 服务器 ， 因 此 ， 人 性 能 这 个 概念 主要 是 从 网 络 角度 出 发 的 ， 它 包含 以 下 
3 个 概念 。 


(1) 网 络 性 能 


这 里 的 网 络 性 能 不 是 针对 一 个 用 户 而 言 的 ， 而 是 针对 Nginx 服 务 而 言 的。 网络 性 能 是 指 
在 不 同 负载 下 ，Web 服 务 在 网 络 通信 上 的 吞吐 量 。 而 带宽 这 个 概念 ， 就 是 指 在 特定 的 网 络 连 
接 上 可 以 达到 的 最 大 吞吐 量 。 因 此 ， 网 络 性 能 肯定 会 受制 于 带宽 ， 当 然 更 多 的 是 受制 于 Web 
服务 的 软件 架构 。 











在 大 多 数 场景 下 ， 随 着 服务 器 上 并 发 连接 数 的 增加 ， 网 络 性 能 部 会 有 所 下 降 。 目 前 ， 我 
们 在 谈 网 络 性 能 时 ， 更 多 的 是 对 应 于 高 并 发 场景 。 例 如 ， 在 几 万 或 者 几 十 万 并 发 连接 下 ， 要 
求 我 们 的 服务 器 仍然 可 以 保持 较 高 的 网 络 否 吐 量 ， 而 不 是 当 并 发 连接 数 达到 一 定数 量 时 ， 服 
务 占 的 CPU 等 资源 大 都 浪费 在 进程 间 切 换 、 休 虐 、 等 街 等 其 他 活动 上 ， 导 致 否 吐 量 大 幅 下 


降 。 
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单 次 请 求 的 延迟 性 与 上 面 说 的 网 络 性 能 的 差别 很 明显 ， 这 里 只 是 针对 一 个 用 户 而 言 的 。 
对 于 Web 服 务 器 ， 延 人 运 性 束 是 指 服 务 占 初次 接收 到 一 个 用 户 请 求 朋 至 返回 啊 应 之 间 持 续 的 时 
间 。 


服务 器 在 低 并 发 和 高 并 发 连接 数量 下 ， 单 个 请 求 的 平均 延迟 时 间 肯 定 是 不 同 的 。Nginx 
在 设计 时 更 应 该 考虑 的 是 在 高 并 发 下 如 何 保持 平均 时 延性 ， 使 其 不 要 上 升 得 太 快 。 








(3) 网 络 效 率 


网 络 效率 很 好 理解 ， 就 是 使 用 网 络 的 效率 。 例 如 ， 使 用 长 连接 〈keepalive) 代 蔡 短 连 接 
以 减少 建立 、 关 闭 连 接 带 来 的 网 络 交 互 ， 使 用 压缩 算法 来 增加 相同 吞吐 量 下 的 信息 携带 量 ， 
使 用 缓存 来 减少 网 络 交 互 次 数 等 ， 它 们 都 可 以 提高 网 络 效率 。 


2. 可 伸缩 性 





可 伸缩 性 指 架 构 可 以 通过 添加 组 件 来 提升 服务 ， 或 者 允许 组 件 之 间 具 有 交互 功能 。 一 般 
可 以 通过 简化 组 件 、 降 低 组 件 间 的 耦合 度 、 将 服务 分 散 到 许多 组 件 等 方法 来 改善 可 伸 纵 性 。 
可 伸缩 性 受到 组 件 间 的 交互 频率 ， 以 及 组 件 对 一 个 请 求 是 使 用 同步 还 是 异步 的 方式 来 处 理 等 
条 件 制约 。 








3. 简 单 性 


简单 性 通 种 指 组 件 的 简单 程度 ， 每 个 组 件 越 简单 ， 惑 会 越 容易 理解 和 实现 ， 也 惑 越 容 易 
被 验证 《被 测试 ) 。 一 般 ， 我 们 通过 分 离 关 注 点 原则 来 设计 组 件 ， 对 于 整体 架构 来 说 ， 通 和 
使 用 通用 性 原则 ， 统 一 组 件 的 接口 ， 这 样 就 减少 了 架构 中 的 变数 。 





4. 可 修改 性 











简单 来 讲 ， 可 修改 性 就 是 在 当前 架构 下 对 于 系统 功能 做 出 修改 的 难 易 程度 ， 对 于 Web 服 
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务 器 来 说 ， 它 还 包括 动态 的 可 修改 性 ， 也 就 是 部 普 好 Web 服 务 器 后 可 以 在 不 停止 、 不 重 局 服 
务 的 前 提 下 ， 提 供给 用 户 不 同 的 、 符 合 需 求 的 功能 。 可 修改 性 可 以 进一步 分 解 为 可 进化 性 、 
可 扩展 性 、 可 定制 性 、 可 配置 性 和 可 重用 性 ， 下 面 简单 说 明 一 下 这 些 概念 。 


(1) 可 进化 性 


可 进化 性 表示 我 们 在 修改 一 个 组 件 时 ， 对 其 他 组 件 产生 负面 影响 的 和 程度。 当然， 每 个 组 
件 的 可 进化 性 都 是 不 同 的 ， 越 是 核心 的 组 件 其 可 进化 性 可 能 会 越 低 ， 也 就 是 说 ， 对 这 个 组 件 
的 功能 做 出 修改 时 可 能 同时 必须 修改 其 他 大 量 的 相关 组 件 。 





对 于 Web 服 务 絮 来 说 , “进化 ”这 个 概念 按照 服务 是 否 在 运行 中 义 可 以 分 为 静态 进化 和 动 
态 进化 。 优 秀 的 静态 进化 主要 依赖 于 染 构 的 设计 是 否 足 够 抽象 ， 而 动态 进化 则 不 然 ， 它 与 整 
个 服务 的 设计 都 是 相关 的 。 


(2) 可 扩展 性 


可 扩展 性 表示 将 一 个 新 的 功能 添加 到 系统 中 的 能 力 《〈 不 影响 其 他 功能 ) 。 与 可 进化 性 一 
样 ， 除 了 静态 可 扩展 性 外 ， 还 有 动态 可 扩展 性 〈 如 果 已 经 部 署 的 服务 在 不 停止 、 不 重启 情况 
下 这 加 新 的 功能 ， 就 称 为 动态 可 扩展 性 ) 。 














(3) 可 定制 性 


可 定制 性 是 指 可 以 临时 性 地 重新 规定 一 个 组 件 或 其 他 架构 元 素 的 特性 ， 从 而 提供 一 种 非 
常规 服务 的 能 力 。 如 果 菏 一 个 组 件 是 可 定制 的 ， 那 么 古 指 用 户 能 够 扩展 该 组 件 的 服务 ， 而 不 
会 对 其 他 客户 产生 影响 。 文 持 可 定制 性 的 风格 一 般 会 提高 简单 性 和 可 扩展 性 ， 因 为 通常 情况 
下 只 会 实现 最 第 用 的 功能 ， 不 太 向 用 的 功能 则 交 由 用 户 重 新 定制 使 用 ， 这 样 组 件 的 复杂 性 就 
降低 了 ， 整 个 服务 也 会 更 容易 扩展 。 





(4) 可 配置 性 
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可 配置 性 是 指 在 Web 服 务 部 区 后 ， 通 过 对 服务 提供 的 配置 文件 进行 修改 ， 来 提供 不 同 的 
功能 。 它 与 可 扩展 性 、 可 重用 性 相关 。 


(5) 可 重用 性 


可 重用 性 指 的 是 一 个 应 用 中 的 功能 组 件 在 不 被 修改 的 情况 下 ， 可 以 在 其 他 应 用 中 重用 的 
程度 。 


S. 可 见 性 





在 Web 服 务 器 这 个 应 用 场景 中 ， 可 见 性 通常 是 指 一 些 关 键 组 件 的 运行 情况 可 以 被 监控 的 
程度 。 例 如 ， 服 务 中 正在 交互 的 网 络 连接 数 、 绥 存 的 使 用 情况 等 。 这 种 监控 ， 可 以 改善 
服务 的 性 能 ， 尤 其 是 可 靠 性 。 


6. 可 移植 性 
可 移植 性 是 指 服 务 可 以 跨 平 台 运 行 ， 这 也 是 当下 Nginx 被 大 规模 使 用 的 必要 条 件 。 
7. 可 靠 性 


可 靠 性 可 以 看 做 是 在 服务 出 现 部 分 故障 时 ， 一 个 染 构 容易 受到 系统 层面 故障 影响 的 程 
度 。 可 以 通过 以 下 方法 提高 可 靠 性 : 避免 单 点 故障 、 增 加 见 余 、 人 允许 监视 ， 以 及 用 可 恢复 的 
动作 来 缩小 故障 的 范围 。 
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8.2 ”Nginx 的 架构 设计 


8.1 节 列 出 了 进行 Nginx 设 计时 需要 格外 重视 的 7 个 关键 点 ， 本 节 将 介绍 Nginx 是 如 何在 这 7 
个 关键 点 上 提升 Nginx 能 力 的 。 


8.2.1 优秀 的 模块 化 设计 


高 度 模块 化 的 设计 是 Nginx 的 架构 基础 。 在 Nginx 中 ， 除 了 少量 的 核心 代码 ， 其 他 一 切 皆 
为 模块 。 这 种 模块 化 设计 同时 具有 以 下 几 个 特点 : 





(1) 高 度 抽象 的 模块 接口 


所 有 的 模块 都 遵循 着 同样 的 ngx_module t 接 口 设计 规范 ， 这 减少 了 整个 系统 中 的 变数 ， 
对 于 8.1 节 中 列 出 的 关键 关注 点 ， 这 种 方式 带 来 了 民 好 的 简单 性 、 静 态 可 扩展 性 、 可 重用 
性。 





(2) 模块 接口 非常 简单 ， 具 有 很 蜗 的 灵活 性 


模块 的 基本 接口 ngx_ module t 足 够 简单 ， 只 涉及 模块 的 初始 化 、 退 出 以 及 对 配置 项 的 处 
理 ， 这 同时 也 带 来 了 足够 的 灵活 性 ， 使 得 Nginx 比 较 简单 地 实现 了 动态 可 修改 性 (参见 8.5 节 
和 8.6 太 ， 可 知 如 何 通 过 HUP 信 号 在 服务 正常 运行 时 使 新 的 配置 文件 生效 ， 以 及 通过 USR2 信 
号 实现 平滑 升级 ) ， 也 就 是 保持 服务 正常 运行 下 使 系统 功能 发 生 改 变 。 





如 图 8-1 所 示 ，ngx_module t 结 构 体 作 为 所 有 模块 的 通用 接口 ， 它 只 定义 了 init_master、 
init module、init process、init thread、exit thread、exit process、exit master 这 7 个 回调 方法 
(事实 上 ，init master、init thread、exit thread 这 3 个 方法 目前 都 没有 使 用 ) ， 它 们 负责 模块 
的 初始 化 和 退出 ， 同 时 它们 的 权限 也 非常 高 ， 可 以 处 理 系统 的 核心 结构 体 ngx_cycle_ t。 在 8.4 
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组 则 指定 了 模块 处 理 配置 项 的 方法 〈 详 见 第 4 章 ) 。 


除了 简单 、 基 础 的 接口 ，ngx_module t 中 的 ctx 成 员 还 是 一 个 void* 指 针 ， 它 可 以 指向 任何 
数据 ， 这 给 模块 提供 了 很 大 的 灵活 性 ， 使 得 下 面 将 要 介绍 的 多 层次 、 多 类 型 的 模块 设计 成 为 
可 能 。ctx 成 员 一 般 用 于 表示 在 不 同类 型 的 模块 中 一 种 类 型 模块 所 具备 的 通用 性 接口 。 











(3) 配置 模块 的 设计 


可 以 注意 到 ，ngx_module t 接 口 有 一 个 type 成 员 ， 它 指明 了 Nginx 人 允许 在 设计 模块 时 定义 
模块 类 型 这 个 概念 ， 允 许 专注 于 不 同 领域 的 模块 按照 类 型 来 区 别 。 而 配置 类 型 模块 是 唯一 一 
种 只 有 1 个 模块 的 模块 类 型 。 配 置 模块 的 类 型 叫做 NGX_CONF MODULE， 它 仅 有 的 模块 叫 
做 ngx_conf module， 这 是 Nginx 最 底层 的 模块 ， 它 指导 着 所 有 模块 以 配置 项 为 核心 来 提供 功 
能 。 因 此 ， 它 是 其 他 所 有 模块 的 基础 。 配 置 模块 使 Nginx 提 供 了 高 可 配置 性 、 高 可 扩展 性 、 
高 可 定制 性 、 高 可 伸缩 性 。 
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+postconfiguration 
+create main conf 
+Hnit main conf 
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+merge srv_conf 
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+merge loc conf 

















ngx module t 






每 种 模块 pu 
将 具体 化 +init process 
ctx 上 下 文 init _thread 


+exit process 
+exit _master 





ngx event module t 


process changes 
+process events 





ngx mail conf ctx t 





中 main conf EE 
+srvy_conf 

3 
图 8-1 ngx_module_t 接 口 及 其 对 核心 、 事 件 、HTIP、mail 等 4 类 模块 ctx 上 下 文成 员 的 具体 化 





(4) 核心 模块 接口 的 简单 化 


Nginx 还 定义 了 一 种 基础 类 型 的 模块 : 核心 模块 ， 它 的 模块 类 型 叫做 
NGX CORE MODULE。 目 前 官方 的 核心 类 型 模块 中 共有 6 个 具体 模块 ， 分 别 是 








nex core module、 ngx errlog module、 ngx events module、 ngx openssl module、 
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ngx_http module、ngx_mail module 模 块 。 为 什么 要 定义 核心 模块 呢 ? 因为 这 样 可 以 简化 Nginx 
的 设计 ， 使 得 非 模 块 化 的 框架 代码 只 关注 于 如 何 调 用 6 个 核心 模块 (大 部 分 Nginx 模 块 都 是 非 
核心 模块 ) 。 


核心 模块 的 接口 非常 简单 ， 如 图 8-1 所 示 ， 它 将 ctk 上 下 文 进 一 步 实 例 化 为 
ngx_core_ module t 结 构 体 ， 代 人 码 如 下 。 





typedef struct { 
// 核心 模块 名 称 


ngx_ str 七 name; 


// 解析 配置 项 前 ， 


Nginx 框 架 会 调用 


create conf 方 法 


void (create conf) (ngx cycle t *cycle); 


// 解析 配置 项 完成 后 ， 


Nginx 框 架 会 调用 


init conf 方 法 


char (init conf) (ngx cycle t cycle, void conf); 
} ngx core module t; 





ngx_core_module_t 上 下 文 是 以 配置 项 的 解析 作为 基础 的 ， 它 所 供 了 create_conf{ 回 调 方 法 
来 创建 存储 配置 项 的 数据 结构 ， 在 读 取 nginx.conf 配 置 文件 时 ， 会 根据 模块 中 的 
ngx_command t 把 解析 出 的 配置 项 存放 在 这 个 数据 结构 中 ; 它 还 提供 了 init_con{ 回 调 方法 ， 用 
于 在 解析 完 配 置 文 件 后 ， 使 用 解析 出 的 配置 项 初始 化 核心 模块 功能 。 除 此 以 外 ，Nginx 框 染 
不 会 约束 核心 模块 的 接口 、 功 能 ， 这 种 人 简洁、 灵活 的 设计 为 Nginx 实 现 动 态 可 配置 性 、 动 态 
可 扩展 性 、 动 态 可 定制 性 带 来 了 极 大 的 便利 ， 这 样 ， 在 每 个 模块 的 功能 实现 中 就 会 较 少 地 考 
碟 如 何不 停止 服务 、 不 重启 服务 来 实现 以 上 功能 


| i [， 交心 模 

















块 ，ngx events module 定 义 了 NGX _ EVENT MODULE 模块 类 型 ， 所 有 事件 类 型 的 模块 都 由 
ngx events_ module 核 心 模 块 管理 ，ngx http _ module 定义 了 NGX _ HTTP _ MODULE 模块 类 型 ， 所 
有 HTTP 类 型 的 模块 都 由 ngx_ http_ module 核 心 模块 管理 ， 而 ngx _ mail module 定 义 了 

NGX _ MAIL MODULE 模块 类 型 ， 所 有 MAI 类 型 的 模块 则 都 由 ngx_mail module 核 心 模块 管 
理 ， 


(5) 多 层次 、 多 类 别 的 模块 设计 


所 有 的 模块 间 是 分 层次 、 分 类 别 的 ， 官 方 Nginx 共 有 五 大 类 型 的 模块 : 核心 模块 、 配 置 
模块 、 事 件 模块 、HTTP 模 块 、mail 模 块 。 虽 然 它 们 都 具备 相同 的 ngx module t 接 口 ， 但 在 请 
求 处 理 流程 中 的 层次 并 不 相同 。 就 如 同上 面 介绍 过 的 核心 模块 一 样 ， 事 件 模 块 、HTTP 模 
块 、mail 模 块 都 会 再 次 具体 化 ngx module t 接 口 〈 由 于 配置 类 型 的 模块 只 拥有 1 个 模块 ， 所 以 
没有 有 具体 化 ck 上 下 文成 员 ) ， 如 图 8-2 所 示 。 





图 8-2 展 示 了 Nginx 常 用 模块 间 的 关系 。 配 置 模块 和 核心 模块 这 两 种 模块 类 型 是 由 Nginx 的 
框架 代码 所 定义 的 ， 这 里 的 配置 模块 是 所 有 模块 的 基础 ， 它 实现 了 最 基本 的 配置 项 解析 功能 
(就 是 解析 nginx.conf 文 件 ) 。Nginx 框 架 还 会 调用 核心 模块 ， 但 是 其 他 3 种 模块 都 不 会 与 框架 
产生 直接 关系 。 事 件 模块 、HTTP 模 块 、mail 模 块 这 3 种 模块 的 共性 是 : 实际 上 它们 在 核心 模 
块 中 各 有 1 个 模块 作为 自己 的 “代言 人 ”， 并 在 同类 模块 中 有 1 个 作为 核心 业务 与 管理 功能 的 模 
块 。 例 如 ， 事 件 模块 是 由 它 的 “代言 人 ”ngx events_module 核 心 模块 定义 ， 所 有 事件 模块 
的 加 载 操 作 不 是 由 Nginx 框 架 完成 的 ， 而 是 由 ngx_event_core_module 模 块 负责 的 。 同 样 ， 
HTTP 模 块 是 由 它 的 “代言 人 ”一 ngx_http module 核 心 模块 定义 的 ， 与 事件 模块 不 同 的 是 ， 这 
个 核心 模块 还 会 负责 加 载 所 有 的 HTTP 模块 ， 但 业务 的 核心 还 辑 以 及 对 于 具体 的 请 求 该 选用 
哪 一 个 HTTP 模 块 处 理 这 样 的 工作 ， 则 是 由 ngx http core module 模 块 决定 的 。 至 于 mail 模 块 ， 
因 与 HTTP 模块 基 本 相似 ， 不 再 歼 述 。 
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mail 模块 


ngx_mall _core _module 


ngx_mail_proxy_module 


ngx_mail ssl] _module 


HTTP 模 块 


ngx_http _core _module 


ngx_http _log _module 


ngx_http _upstream_module 


ngx_http _static _module 


事件 模块 


ngx_select _ module 


ngx_poll_ module 


ngx_mail_imap_ module 
ngx_mail_pop3_module 


ngx_mail_smtp_module 


ngx_http _headers_filter _ module 


ngx_http _write _filter _module 


ngx_http _rewrite _ module 


ngx_http _proxy_module 


ngx_epoll _module 


ngx_kqueue_module 


ngx_aio _module 


Ne 和 





图 8-2 Nginx 常 用 模块 及 其 之 间 的 关系 


核心 模块 


ngx_mail_module 


(定义 mail 模 块 ) 


ngx_http _module 


(定义 HTTP 模块 ) 


ngx_openss| _module 


ngx_events _module 


(定义 事件 模块 ) 


ngx_core _module 


在 这 5 种 模块 中 ， 配 置 模块 与 核心 模块 都 是 与 Nginx 框 架 密切 相关 的 ， 是 其 他 模块 的 基 
础 。 而 事件 模块 则 是 HTTP 模 块 和 mail 模 块 的 基础 ， 原 因 参 见 8.2.2 市 。HTTP 模 块 和 mail 模 块 
的 “地 位 ”相似 ， 它 们 都 更 关注 于 应 用 层面 。 在 事件 模块 中 ，ngx event core module 事件 模块 
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是 其 他 所 有 事件 模块 的 基础 ， 在 HTTP 模 块 中 ，ngx http core module 模 块 是 其 他 所 有 HTTP 模 
块 的 基础 ， 在 mail 模 块 中 ，ngx_mail _ core _ module 模块 是 其 他 所 有 mail 模 块 的 基础 。 


8.2.2 ”事件 驱动 架构 








所 谓 事 件 驱 动 染 构 ， 简 单 来 说 ， 就 是 由 一 些 事件 发 生源 来 产生 事件 ， 由 一 个 或 者 多 个 事 
件 收集 器 来 收集 、 分 发 事件 ， 然 后 许多 事件 处 理 顺 会 注册 目 己 感 兴趣 的 事件 ， 同 时 会 “ 消 
费 ” 这 些 事件 。 





对 于 Nginx 这 个 Web 服 务 器 而 言 ， 一 般 会 由 网 卡 、 人 磁盘 产生 事件 ， 而 8.2.1 节 中 提 到 的 事件 
模块 将 负责 事件 的 收集 、 分 发 操作 ， 而 所 有 的 模块 都 可 能 是 事件 消费 者 ， 它 们 首先 需要 向 事 
件 模块 注册 感 兴趣 的 事件 类 型 ， 这 样 ， 在 有 事件 产生 时 ， 事 件 模块 会 把 事件 分 发 到 相应 的 模 
块 中 进行 处 理 。 





Nginx 采 用 完全 的 事件 驱动 染 构 来 处 理 业 务 ， 这 与 传统 的 Web 服 务 器 (如 Apache〉 是 不 同 
的 。 对 于 传统 Web 服 务 器 而 言 ， 采 用 的 所 谓 事件 驱动 往往 局 限 在 TCP 连 接 建立 、 关 闭 事 件 
上 ， 一 个 连接 建立 以 后 ， 在 其 关闭 之 前 的 所 有 操作 都 不 再 是 事件 驱动 ， 这 时 会 退化 成 按 序 执 
行 每 个 操作 的 批 处 理 模式 ， 这 样 每 个 请 求 在 连接 建立 后 都 将 始终 占用 着 系统 资源 ， 直 到 连接 
天 有 财 才 会 释放 资源 。 要 知道 ， 这 段 时 间 可 能 会 非常 长 ， 从 1 至 秒 到 1 分 钟 都 有 可 能 ， 而 且 这 段 
时 间 内 占用 独 内 存 、CPU 等 资源 也 许 并 没有 意义 ， 整 个 事件 消费 进程 只 是 在 等 待 茶 个 条 件 而 
己 ， 造 成 了 服务 器 资源 的 极 大 浪费 ， 影 响 了 系统 可 以 处 理 的 并 发 连接 数 。 如 图 8-3 所 示 ， 这 
种 传统 Web 服 务 器 往往 把 一 个 进程 或 线程 作为 事件 消费 者 ， 当 一 个 请 求 产 生 的 事件 被 该 进程 
处 理 时 ， 直 到 这 个 请 求 处 理 结束 时 进程 资源 都 将 被 这 一 个 请 求 所 占用 。 
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图 8-3 ”传统 Web 服 务 器 处 理事 件 的 简单 模型 (椭圆 代表 数据 结构 ， 撼 形 代 表 进 程 ) 








Nginx 则 不 然 ， 它 不 会 使 用 进程 或 线程 来 作为 事件 消费 者 ， 所 谓 的 事件 消费 者 只 能 是 茶 
个 模块 〈 在 这 里 没有 进程 的 概念 ) 。 只 有 事件 收集 、 分 发 堪 才 有 资格 占用 进程 资源 ， 它 们 会 
在 分 发 茶 个 事件 时 调用 事件 消费 模块 使 用 当前 占用 的 进程 资源 ， 如 图 8-4 所 示 。 








图 8-4 中 列 出 了 5 个 不 同 的 事件 ， 在 事件 收集 、 分 发 者 进程 的 一 次 处 理 过 程 中 ， 这 5 个 事 
件 按照 顺序 被 收集 后 ， 将 开始 使 用 当前 进程 分 友 事 件 ， 从 而 调用 相应 的 事件 消费 者 模块 来 处 
理事 件 。 当 然 ， 这 种 分 发 、 调 用 也 是 有 序 的 。 








从 上 面 的 内 容 可 以 看 出 传统 Web 服 务 器 与 Nginx 间 的 重要 差别 :前 者 是 每 个 事件 消费 者 独 
占 一 个 进程 资源 ， 后 者 的 事件 消费 者 只 是 被 事件 分 发 者 进程 短期 调用 而 已 。 这 种 设计 使 得 网 
络 性 能 、 用 户 感知 的 请 求 时 延 〈 延 时 性 ) 都 得 到 了 提升 ， 每 个 用 户 的 请 求 所 产生 的 事件 会 及 
时 响应 ， 整 个 服务 器 的 网 络 吞 吐 量 都 会 由 于 事件 的 及 时 响应 而 增 大 。 但 这 也 会 带 来 一 个 重要 
的 次 端 ， 即 每 个 事件 消费 者 都 不 能 有 阻塞 行为 ， 否 则 将 会 由 于 长 时 间 占 用 事件 分 发 者 进程 而 
导致 其 他 事件 得 不 到 及 时 响应 。 尤 其 是 每 个 事件 消费 者 不 可 以 让 进程 转变 为 休眠 状态 或 等 待 
状态 ， 如 在 等 待 一 个 信号 量 条 件 的 满足 时 会 使 进程 进入 休眠 状态 。 这 加 大 了 事件 消费 程序 的 
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开发 者 的 编程 难度 ， 因 此 ， 这 也 导致 了 Nginx 的 模块 开发 相对 于 Apache 来 说 复杂 不 少 ( 上 文 
己 经 提 到 过 ) 。 
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图 8-4 Nginx 处 理事 件 的 简单 模型 


8.2.3 ”请 求 的 多 阶段 异步 处 理 


这 里 所 讲 的 多 阶段 异步 处 理 请 求 与 事件 驱动 架构 是 密切 相关 的 ， 换 句 话 说 ， 请 求 的 多 阶 
段 异 步 处 理 只 能 基于 事件 驱动 架构 实现 。 什 么 意思 呢 ? 就 是 把 一 个 请 求 的 处 理 过 程 按 照 事件 
的 触发 方式 划分 为 多 个 阶段 ， 每 个 阶段 都 可 以 由 事件 收集 、 分 及 器 来 触 友 。 





例如 ， 处 理 一 个 获取 静态 文件 的 HTTP 请 求 可 以 分 为 以 下 几 个 阶段 ( 见 表 8-1)。 
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表 8-1 处 理 获取 静态 文件 的 HTTP 请 求 时 切 分 的 阶段 及 各 阶段 的 触发 事件 


阶段 意义 触发 事件 
建 半 TOP 连接 接收 到 TCP 中 的 SYN 包 
开始 接收 用 户 请 求 接收 到 TCP 中 的 ACK 包 表 示 连 接 建立 成 功 
接收 到 用 户 请 求 并 分 析 已 接收 的 请 求 是 否 完整 接收 到 用 户 的 数据 包 
接收 到 完整 的 用 户 请 求 后 开始 处 理 用 户 请 求 接收 到 用 户 的 数据 包 
由 目标 静态 文件 中 读 取 部 分 内 容 (避免 长 期 阻塞 事 | 接收 到 用 户 的 数据 包 ; 或 者 接收 到 TCP 中 的 ACK 包 表 示 
件 分 发 者 进程 ) 并 直接 发 送 给 用 户 用 户 已 接收 到 上 次 发 送 的 数据 包 ，TCP 滑动 窗口 向 前 滑动 
( 续 ) 
阶段 意义 触发 事件 
对 于 非 keep-alive 请 求 ， 在 发 送 完 静态 文件 后 主动 | 接收 到 TCP 中 的 ACK 包 表 示 用 户 已 接收 到 之 前 发 送 的 所 
关闭 连接 和 
由 于 用 户 关闭 连接 而 结束 请 求 人 


这 个 例子 中 大 致 分 为 7 个 阶段 ， 这 些 阶段 是 可 以 重复 发 生 的 ， 因 此 ， 一 个 下 载 静态 资源 
请 求 可 能 会 由 于 请 求 数 据 过 大 、 网 速 不 稳定 等 因素 而 被 分 解 为 成 百 上 干 个 表 8-1 中 所 列 出 的 
阶段 。 


异步 处 理 和 多 阶段 是 相辅相成 的 ， 只 有 把 请 求 分 为 多 个 阶段 ， 才 有 所 谓 的 异步 处 理 。 也 
就 是 说， 当 一 个 事件 被 分 发 到 事件 消费 者 中 进行 处 理 时 ， 事 件 消费 者 处 理 完 这 个 事件 只 相当 
于 处 理 完 1 个 请 求 的 茶 个 阶段 。 什 么 时 候 可 以 处 理 下 一 个 阶段 呢 ? 这 只 能 等 竺 内核 的 通知 ， 
即 当 下 一 次 事件 出 现时 ，epoll 等 事件 分 有 器 将 会 获取 到 通知 ， 再 继续 调用 事件 消费 者 处 理 请 
求 。 这 样 ， 每 个 阶段 中 的 事件 消费 者 都 不 清楚 本 次 完整 的 操作 完 苋 什么 时 候 会 完成 ， 只 能 异 
步 被 动 地 等 待 下 一 次 事件 的 通知 。 

















请 求 的 多 阶段 异步 处 理 优势 在 哪里 ? 这 种 设计 配合 事件 驱动 架构 ， 将 会 极 大 地 提高 网 络 
性 能 ， 同 时 使 得 每 个 进程 都 能 全 力 运 转 ， 不 会 或 者 尽量 少 地 出 现 进程 休眠 状况 。 因 为 一 旦 出 
现 进程 休眠 ， 必 然 减少 并 发 处 理事 件 的 数目 ， 一 定 会 降低 网 络 性 能 ， 同 时 会 增加 请 求 处 理 时 
间 的 平均 时 延 ! 这 时 ， 如 果 网 络 性 能 无 法 满足 业务 需求 将 只 能 增加 进程 数目 ， 进 程 数目 过 多 
就 会 增加 操作 系统 内 核 的 额外 操作 : 进程 间 切 换 ， 可 是 频繁 地 进行 进程 间 切 换 仍 会 消耗 CPU 
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等 资源 ， 从 而 降低 网 络 性 能 。 同 时 ， 休 虐 的 进程 会 使 进程 占用 的 内 存 得 不 到 有 效 释放 ， 这 最 
终 必然 导致 系统 可 用 内 存 的 下 降 ， 从 而 影响 系统 能 够 处 理 的 最 大 并 发 连接 数 。 


根据 什么 原则 来 划分 请 求 的 阶段 呢 ? 一 般 是 找到 请 求 处 理 流 程 中 的 阻塞 方法 《或 者 造成 
阻塞 的 代码 段 ) ， 在 阻 守 代 码 段 上 按照 下 面 4 种 方式 来 划分 阶段 : 


(1) 将 阻 赛 进 程 的 方法 按照 相关 的 触发 事件 分 解 为 两 个 阶段 


一 个 本 映 可 能 导致 进程 休眠 的 方法 或 系统 调用 ， 一 般 都 能 够 分 解 为 多 个 更 小 的 方法 或 者 
系统 调用 ， 这 些 调 用 间 可 以 通过 事件 触发 天 联 起 来 。 大 部 分 情况 下 ， 一 个 阻 竖 进程 的 方法 调 
用 时 可 以 划分 为 两 个 阶段 : 阻塞 方法 改 为 非 阻塞 方法 调用 ， 这 个 调用 非 阻塞 方法 并 将 进程 归 
还 给 事件 分 发 器 的 阶段 束 是 第 一 阶段 ;增加 新 的 处 理 阶段 〈 第 二 阶段 ) 用 于 处 理 非 阻塞 方法 
最 终 返 回 的 结果 ， 这 里 的 结果 返回 事件 就 是 第 二 阶段 的 触发 事件 。 





例如 ， 在 使 用 send 调 用 发 送 数据 给 用 户 时 ， 如 宁 使 用 阻塞 socket 句 柄 ， 那 么 send 调 用 在 加 
操作 系统 内 核发 出 数据 包 后 就 必须 把 当前 进程 休眠 ， 直 到 成 功 发 出 数据 才能 “ 醒 来 "。 这 时 的 
send 调 用 发 送 数据 并 等 竺 结果。 我 们 需要 把 send 调 用 分 解 为 两 个 阶段 : 发 送 且 不 等 待 结果 阶 
段 、send 结 果 返 回 阶段 。 因 此 ， 可 以 使 用 非 阻 塞 socket 句 柄 ， 这 样 调用 send 发 送 数据 后 ， 进 程 
古 不 会 进入 休 虐 的 ， 这 束 是 发 送 且 不 等 待 结果 阶段 ， 再 把 socket 句 柄 加 入 到 事件 收集 絮 中 就 
可 以 等 每 相应 的 事件 触发 下 一 个 阶段 ，send 发 送 的 数据 被 对 方 收 到 后 这 个 事件 束 会 触及 send 
结果 返回 阶段 。 这 个 send 调 用 就 是 请 求 的 划分 阶段 点 。 





(2) 将 阻 蹇 方法 调用 按照 时 间 分 解 为 多 个 阶段 的 方法 调用 

注意 ， 系 统 中 的 事件 收集 、 分 发 者 并 非 可 以 处 理 任 何事 件 。 如 果 按 照 前 一 种 方式 试图 划 
分 某 个 方法 时 ， 那 么 可 能 会 发 现 找 出 的 触发 事件 不 能 够 被 事件 收集 、 分 发 需 所 处 理 ， 这 时 只 
能 按照 执行 时 间 来 拆 分 这 个 方法 了 。 





例如 读 取 文件 的 调用 《〈 非 异步 JO) ， 如 果 我 们 读 取 10MB 的 文件 ， 这 些 文 件 在 磁盘 中 的 
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块 未 必 是 连续 的 ， 这 意味 着 当 这 10MB 文 件 内 容 不 在 操作 系统 的 缓存 中 时 ， 可 能 需要 多 次 驱 
动 硬盘 寻 址 。 在 寻 址 过 程 中 ， 进 程 多 半 会 休眠 或 者 等 待 。 我 们 可 能 会 希望 像 上 文 所 说 的 那样 
把 读 取 文件 调用 分 解 成 两 个 阶段 发 送 读 取 命 令 且 不 等 待 结果 阶段 、 读 取 结 果 返 回 阶段 。 这 
样 当然 很 好 ， 可 惜 的 是 ， 如 果 我 们 的 事件 收集 、 分 发 者 不 支持 这 么 做 ， 该 怎么 办 ? 例如， 在 
Linux 上 Nginx 的 事件 模块 在 没 打 开 异步 WO 时 就 不 支持 这 种 方法 ， 像 ngx_epoll module 模 块 主要 
是 针对 网 络 事件 的 ， 而 主机 的 磁盘 事件 目前 还 不 支持 〈 必 须 通过 内 核 异 步 J0) 。 这 时 ， 我 
们 可 以 这 样 来 分 解读 取 文 件 调 用 : 把 10MB 均 分 成 1000 份 ， 每 次 只 读 取 10KB。 这 样 ， 读 取 

10KB 的 时 间 就 是 可 控 的 ， 意 味 着 这 个 事件 接收 器 占用 进程 的 时 间 不 会 太 久 ， 整 个 系统 可 以 
及 时 地 处 理 其 他 请 求 。 














那么 ， 在 读 取 0KB~10KB 的 阶段 完成 后 ， 怎 样 进入 10KB~20KB 阶 段 呢 ? 这 有 很 多 种 方 
式 ， 如 读 取 完 10KB 文 件 后 ， 可 能 需要 使 用 网 络 来 发 送 它 们 ， 这 时 可 以 由 网 络 事件 来 触发 。 
或 者 ， 如 果 没 有 网 络 事件 ， 也 可 以 设置 一 个 简单 的 定时 器 ， 在 某 个 时 间 点 后 再 次 调用 下 一 个 
阶段 。 








(3) 在 “无 所 事 事 ” 且 必须 等 待 系统 的 啊 应 ， 从 而 导致 进程 空转 时 ， 使 用 定时 器 划分 阶 


有 时 阻塞 的 代码 段 可 能 是 这 样 的 : 进行 共 个 无 阻塞 的 系统 调用 后 ， 必 须 通 过 持续 的 检查 
标志 位 来 确定 是 否 继续 癌 下 执行 ， 当 标志 位 没有 获得 满足 时 就 循环 地 检查 下 去 。 这 样 的 代码 
段 本 身 没有 阻 竖 方法 调用 ， 可 实际 上 有 是 阻塞 进程 的 。 这 时 ， 应 该 使 用 定时 器 来 代 珍 循环 检查 
标志 ， 这 样 定时 右 事 件 发 生 时 就 会 先 检查 标志 ， 如 果 标 志 位 不 满足 ， 就 立刻 归还 进程 控制 
权 ， 同 时 继续 加 入 期 望 的 下 一 个 定时 器 事件 。 











(4) 如 果 阻 塞 方法 完全 无 法 继续 划分 ， 则 必须 使 用 独立 的 进程 执行 这 个 阻塞 方法 


如 果 某 个 方法 调用 时 可 能 导致 进程 休眠 ， 或 者 占用 进程 时 间 过 长 ， 可 是 又 无 法 将 该 方法 
分 解 为 不 阻塞 的 方法 ， 那 么 这 种 情况 是 与 事件 驱动 架构 相 违背 的 。 通 常 是 由 于 这 个 方法 的 实 
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现 者 没有 开放 非 阻 塞 接口 所 导致 ， 这 时 必须 通过 产生 新 的 进程 或 者 指定 某 个 非 事件 分 发 者 进 
程 来 执行 阻塞 方法 ， 并 在 阻塞 方法 执行 完毕 时 向 事件 收集 、 分 发 者 进程 发 送 事件 通知 继续 执 
行 。 因此， 至 少 要 拆 分 为 两 个 阶段 :阻塞 方法 执行 前 阶段 、 阻 塞 方 法 执行 后 阶段 ， 而 阻塞 方 
法 的 执行 要 使 用 单独 的 进程 去 调度 ， 并 在 方法 返回 后 发 送 事 件 通知 。 一 旦 出 现 上 面 这 种 设 

计 ， 我 们 必须 审视 这 样 的 事件 消费 者 是 否 足 够 合理 ， 有 没有 必要 用 这 种 违反 事件 驱动 架构 的 
方式 来 解决 阻 罕 问 题 











请 求 的 多 阶段 异步 处 理 将 会 提高 网 络 性 能 、 降 低 请 求 的 时 延 ， 在 与 事件 驱动 架构 配合 工 
作 后 ， 可 以 使 得 Web 服 务 器 同时 处 理 十 万 甚至 百 万 级 别 的 并 发 连接 ， 我 们 在 开发 Nginx 模 块 时 
必须 遵循 这 一 原则 。 


8.2.4 管理 进程 、 多 工作 进程 设计 


Nginx 采 用 一 个 master 管 理 进 程 、 多 个 worker 工 作 进 程 的 设计 方式 ， 如 图 8-$ 所 示 。 
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图 8-5 Nginx 采 用 的 一 个 mastet 管 理 进程 、 多 个 工作 进程 的 设计 方式 


在 图 8-$ 中 ， 包 括 完 全 相同 的 worker 进 程 、1 个 可 选 的 cache manager 进 程 以 及 1 个 可 选 的 


cache loader 进 程 。 
这 种 设计 带 来 以 下 优点 : 


(1) 利用 多 核 系 统 的 并 发 处 理 能 
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现代 操作 系统 已 经 文 持 多 核 CPU 架 构 ， 这 使 得 多 个 进程 可 以 占用 不 同 的 CPU 核 心 来 工 
作 。 如 果 只 有 一 个 进程 在 处 理 请 求 ， 则 必然 会 造成 CPU 资 源 的 浪费 ! 如 果 多 个 进程 间 的 地 位 
不 平等 ， 则 必然 会 有 茶 一 级 同一 地 位 的 进程 成 为 瓶颈 ， 因 此 ，Nginx 中 所 有 的 worker 工 作 进 
程 都 是 完全 平等 的 。 这 提高 了 网 络 性 能 、 降 低 了 请 求 的 时 延 。 


(2) 负载 均衡 


多 个 worker 工 作 进程 间 通 过 进程 间 通 信 来 实现 负载 均衡 ， 也 就 是 次 ， 一 个 请 求 到 来 时 更 
容易 被 分 配 到 负载 较 轻 的 worker 工 作 进程 中 处 理 。 这 将 降低 请 求 的 时 延 ， 并 在 一 定 程度 上 提 
高 网 络 性 能 


(3) 管理 进程 会 负责 监控 工作 进程 的 状态 ， 并 负责 管理 其 行为 





管理 进程 不 会 占用 多 少 系 统 资源 ， 它 只 是 用 来 局 动 、 停 止 、 监 控 或 使 用 其 他 行为 来 控制 
工作 进程 。 首 先 ， 这 提高 了 系统 的 可 靠 性 ， 当 工作 进程 出 现 问题 时 ， 管 理 进程 可 以 局 动 新 的 
工作 进程 来 避免 系统 性 能 的 下 降 。 其 次 ， 管 理 进程 支持 Nginx 服 务 运行 中 的 程序 升级 、 配 置 
项 的 修改 等 操作 ， 这 种 设计 使 得 动态 可 扩展 性 、 动 态 定 制 性 、 动 态 可 进化 性 较 容 易 实 现 。 





8.2.5 平台 无 关 的 代码 实现 


在 使 用 C 语 言 实现 Nginx 时 ， 尽 量 减少 使 用 与 操作 系统 平台 相关 的 代码 ， 如 茶 个 操作 系统 
上 的 第 三 方 库 。Nginx 重 新 封装 了 日 疡 、 各 种 基本 数据 结构 《如 第 7 章 中 介绍 的 容 胡 ) 、 负 用 
算法 等 工具 软件 ， 在 核心 代码 都 使 用 了 与 操作 系统 无 关 的 代码 实现 ， 在 与 操作 系统 相关 的 系 
统 调用 上 则 分 别针 对 各 个 操作 系统 都 有 独立 的 实现 ， 这 最 终 造 就 了 Nginx 的 可 移植 性 ， 实 现 
了 对 主流 操作 系统 的 文 持 。 








8.2.6 内存 池 的 设计 
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为 了 避免 出 现 内 存 碎 片 、 减 少 同 操 作 系统 申请 内 存 的 次 数 、 降 低 各 个 模块 的 开 及 复杂 
度 ，Nginx 设 计 了 简单 的 内 存 池 。 这 个 内 存 池 没有 很 复杂 的 功能 它 不 负责 回收 内 存 池 
中 己 经 分 配 出 的 内 存 。 这 种 内 存 池 最 大 的 优点 在 于 : 把 多 次 同系 统 申请 内 存 的 操作 整合 成 一 
次 ， 这 大 大 减少 了 CPU 资源 的 消耗 ， 同 时 减少 了 内 存 碎片 。 





因此 ， 通 常 每 一 个 请 求 都 有 一 个 这 种 简易 的 独立 内 存 池 【在 第 9 章 中 会 看 到 ，Nginx 为 每 
一 个 TCP 连 接 都 分 配 了 1 个 内 存 池 ， 而 在 第 10 草 和 第 11 音 ，HTTP 框 架 为 每 一 个 HTTP 请 求 又 分 
配 了 1 个 内 存 池 ) ， 而 在 请 求 结束 时 则 会 销毁 整个 内 存 池 ， 把 兽 经 分 配 的 内 存 一 次 性 归还 给 
操作 系统 。 这 种 设计 大 大 提高 了 模块 开发 的 简单 性 (如 在 前 几 间 中 开发 HTTP 模 块 时 ， 申 请 
内 存 后 都 不 用 关心 它 释 放 的 问题 ， 而 且 因 为 分 配 内 存 次 数 的 减少 使 得 请 求 执行 的 时 延 得 到 
了 降低 ， 同 时 ， 通 过 减少 内 存 碎片 ， 提 高 了 内 存 的 有 效 利 用 率 和 系统 可 处 理 的 并 发 连接 数 ， 
从 而 增强 了 网 络 性 能 








8.2.7 ”使 用 统一 管道 过 滤器 模式 的 HTTP 过 滤 模 块 


有 一 类 HTTP 模 块 被 命名 为 HTTP 过 小 模块 ， 其 中 每 一 个 过 滤 模 块 都 有 输入 端 和 输出 站 ， 
这 些 输入 端 和 输出 端 都 有 具有 统一 的 接口 。 这 些 过 滤 模 块 将 按照 configure 执 行 时 决定 的 顺序 组 
成 一 个 流水 线 式 的 加 工 HTTP 响 应 的 中 心 ， 每 一 个 过 滤 模 块 都 是 完全 独立 的 ， 它 处 理 着 输入 
端 接收 到 的 数据 ， 并 由 输出 端 传递 给 下 一 个 过 滤 模 块 。 过 滤 模 块 都 必须 可 以 增 量 地 处 
理 数据 ， 也 就 是 说 能 够 正确 处 理 完整 数据 流 的 一 部 分 





这 种 统一 管理 过 滤器 的 设计 方式 的 好 处 非常 明显 : 首先 它 允 许 把 整个 HTTP 过 小 系统 的 
输入 /输出 简化 为 一 个 个 过 小 模块 的 简单 组 合 ， 这 大 大 提高 了 简单 性 ， 其次， 它 提供 了 很 好 
的 可 重用 性 ， 任 意 两 个 HTTP 过 渡 模 块 剖 可 以 连接 在 一 起 (在 可 允许 的 范围 内 ) ; 再 次 ， 整 
个 过 涯 系统 非常 容易 维护 、 增 强 。 例 如 ， 开 及 了 一 个 新 的 过 涯 模块 后 ， 可 以 非常 方便 地 添加 
到 过 滤 系 统 中 ， 这 是 一 种 高 可 扩展 性 。 又 如 ， 旧 的 过 滤 模 块 可 以 很 容易 地 被 升级 版 的 过 滤 模 


块 所 替代 ， 这 是 一 种 高 可 进化 性 ， 接 着 ， 它 在 可 验证 性 和 可 测试 性 上 非常 友好 ， 我 们 可 以 灵 
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活 地 变动 这 个 过 滤 模 块 流水 线 来 验证 功能 ;， 最后， 这样 的 系统 完全 文 持 并 发 执行 。 


8.2.8 ”其 他 一 些 用 户 模 块 


Nginx 还 有 许多 特定 的 用 户 模块 都 会 改进 8.1 节 中 提 到 的 约束 属性 。 例 如 ， 
ngx_ http_ stub_status _ module 模 块 提供 对 所 有 HTTP 连 接 状态 的 监控 ， 这 就 提高 了 系统 可 见 性 。 
而 ngx_http gzip filter module 过 滤 模 块 和 ngx http_gzip_static_ module 模 块 使 得 相同 的 吞吐 量 传 
送 了 更 多 的 信息 ， 自 然 也 就 提高 了 网 络 效率 。 我 们 也 可 以 开发 这 样 的 模块 ， 让 Nginx 变 得 更 
好 
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8.3 ”Neginx 框 架 中 的 核心 结构 体 ngx cycle t 


Nginx 核 心 的 框 染 代 码 一 直 在 围绕 着 一 个 结构 体 展开 ， 它 就 是 ngx_cycle_t。 无 论 丰 master 
管理 进程 、worker 工 作 进程 还 是 cache manager (loader) 进程 ， 每 一 个 进程 都 毫 无 例外 地 拥 
有 了 唯一 一 个 ngx_cycle t 结 构 体 。 服 务 在 初始 化 时 就 以 ngx_cycle_t 对 象 为 中 心 来 提供 服务 ， 在 
正常 运行 时 仍然 会 以 ngx_cycle_t 对 象 为 中 心 。 本 万 将 围绕 着 ngx_cycle t 结 构 体 的 定义 、 
ngx_cycle_t 结 构 体 所 支持 的 方法 来 介绍 Nginx 框 架 代 码 ， 其 中 8.4 市 中 的 Nginx 的 局 动 流程 、8.5 
市 和 8.6 太 中 Nginx 各 进程 的 主要 工作 流程 都 古 以 ngx_cycle_t 结 构 体 作为 基础 的 。 下 面 我 们 来 
看 一 下 ngx_cycle t 究 范 有 哪些 成 员 维 持 了 Nginx 的 基本 框架 。 


8.3.1 ngx listening t 结 构 体 





作为 一 个 Web 服 务 器 ，Nginx 首 先 需要 监听 端口 并 处 理 其 中 的 网 络 事件 。 这 本 来 应 该 属于 
第 9 章 所 介绍 的 事件 模块 要 处 理 的 内 容 ， 但 由 于 监听 端口 这 项 工作 是 在 Nginx 的 启动 框架 代码 
中 完成 的 ， 所 以 暂时 把 它 放 到 本 章 中 介绍 。ngx_ cycle _t 对 象 中 有 一 个 动态 数组 成 员 叫 做 
listening， 它 的 每 个 数组 元 素 都 是 ngx_listening t 结 构 体 ， 而 每 个 ngx_listening t 结 构 体 又 代表 
着 Nginx 服 务 器 监听 的 一 个 端口 。 在 8.3.2 节 中 的 一 些 方法 会 使 用 ngx_listening t 结 构 体 来 处 理 
要 监听 的 端口 ， 在 8.4 节 中 我 们 也 会 看 到 master 进 程 、worker 进 程 等 许多 进程 如 何 监 听 同 一 个 
TCP 端 口 (fork 出 的 子 进程 自然 共享 打开 的 端口 ) 。 更 多 关于 ngx_ listening t 的 介绍 将 在 第 9 章 
中 介绍 。 本 节 我 们 仅仅 介绍 ngx listening t 的 成 员 ， 对 于 它 会 引用 到 的 其 他 对 象 ， 如 
ngx_connection t 等 ， 将 在 第 9 章 中 介绍 。 下 面 来 看 一 下 ngx_listening t 的 成 员 ， 代 码 如 下 所 


砂 。 
typedef struct ngx listening s ngx listening t; Struct ngx listening s { 


// socket 套 接 字 句柄 
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ngx socket 七 fq; 


// 监听 


sockaddr 地 址 


struct sockaddr *sockaddr; 


// sockaddr 地 址 长 度 


socklen t socklen; 


/* 存 储 


IP 地 址 的 字符 串 


addr text 最 大 长 度 ， 即 它 指定 了 


addr_text 所 分 配 的 内 存 大 小 


4 


size 七 addr text max len; 





// 以 字符 串 形 式 存储 


IP 地 址 


ngx str t addr text; 


// 套 接 字 类 型 。 例 如 ， 当 


se 十 nn http://ww li nuxorobe. con 





SOCK_ STREAM 时 ， 表 示 





TCP 
int type; 
/*TCP 实 现 监听 时 的 
backlog 队 列 ， 它 表示 允许 正在 通过 三 次 握手 建立 
TCP 连 接 但 还 没有 任何 进程 开始 处 理 的 连接 最 大 个 数 
*/ 
int backlog; 


// 内 核 中 对 于 这 个 套 接 字 的 接收 缓冲 区 大 小 


ob 


// 内 核 中 对 于 这 个 套 接 字 的 发 送 缓冲 区 大 小 


int sndbuf; 
// 当 新 的 


TCP 连 接 成 功 建立 后 的 处 理 方法 


ngx connection handler pt handler; /* 实 际 上 框架 并 不 使 用 
servers 指 针 ， 它 更 多 是 作为 一 个 保留 指针 ， 目 前 主要 用 于 


HTTP 或 者 
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mail 等 模块 ， 用 于 保存 当前 监听 端口 对 应 着 的 所 有 主机 名 


G4 


void *servers; 


// log 和 


logp 都 是 可 用 的 日 志 对 象 的 指针 


ngx log t log; 


ngx log 七 *logp; 


// 如 果 为 新 的 


TCP 连 接 创 建 内 存 池 ， 则 内 存 池 的 初始 大 小 应 该 是 


pool size 


size t pool size; 


/*TCP_DEFER ACCEPT 选 项 将 在 建立 








TCP 连 接 成 功 且 接收 到 用 户 的 请 求 数据 后 ， 才 向 对 监听 套 接 字 感 兴趣 的 进程 发 送 事件 通知 ， 而 连接 建立 成 功 后 ， 如 果 


post_accept timeout 秒 后 仍然 没有 收 到 的 用 户 数据 ， 则 内 核 直 接 丢 弃 连 接 


4 


ngx msec t post accept timeout; 





/* 前 一 个 
ngx listening 七 结构 ， 多 个 


ngx listening 七 结构 体 之 间 由 
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Previous 指 针 组 成 单 链 表 


G4 
ngx listening t *previous; 
// 当前 监听 句柄 对 应 着 的 
ngx connection t 结 构 体 
ngx connection t *connection; 
/* 标 志 位 ， 为 
1 则 表示 在 当前 监听 句柄 有 效 ， 且 执行 
ngx init cycle 时 不 关闭 监听 端口 ， 为 
0 时 则 正常 关闭 。 该 标志 位 框架 代码 会 自动 设置 
*/ 


unsigned open:1; 
/* 标 志 位 ， 为 
1 表示 使 用 已 有 的 
ngx _ cycle 七 来 初始 化 新 的 
ngx_cycle 七 结 构 体 时 ， 不 关闭 原先 打开 的 监听 端口 ， 这 对 运行 中 升级 程序 很 有 用 ， 
remain 为 
0 时 ， 表 示 正 常 关闭 曾经 打开 的 监听 端口 。 该 标志 位 框架 代码 会 自动 设置 ， 参 见 


ngx_ init cycle 方 法 
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5/ 


unsigned remain:1; 


1 时 表示 跳 过 设置 当前 


ngx listening 七 结构 体 中 的 套 接 字 ， 为 


0 时 正常 初始 化 套 楼 字 。 该 标志 位 框架 代码 会 自动 设置 


*/ 
unsigned ignore:1; 
// 表示 是 否 已 经 绑 定 。 实 际 上 目前 该 标志 位 没有 使 用 
unsigned bound:1; /* 已 经 绑 定 

*/ 
/* 表 示 当 前 监听 向 柄 是 否 来 自前 一 个 进程 (如 升级 


Nginx 程 序 ) ， 如 果 为 
1， 则 表示 来 自前 一 个 进程 。 一 般 会 保留 之 前 已 经 设置 好 的 套 接 字 ， 不 做 改变 
4 
unsigned inherited:1; ”/* 来 自前 一 个 进程 
4 


// 目前 未 使 用 
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// 标志 位 ， 为 


1 时 表示 当前 结构 体 对 应 的 套 接 字 已 经 监听 


unsigned listen:1; 


// 表示 套 接 字 是 否 阻塞 ， 目 前 该 标志 位 没有 意义 


unsigned nonblocking:1; 


// 目前 该 标志 位 没有 意义 


unsigned shared:1; 


// 标志 位 ， 为 


1 时 表示 


Nginx 会 将 网 络 地 址 转变 为 字符 串 形 式 的 地 址 


unsigned addr ntop:1; 





ngx connection handler pt 类 型 的 handler 成 员 表 示 在 这 个 监听 端口 上 成 功 建立 新 的 TCP 连 
接 后 ， 就 会 回调 handler 方 法 ， 它 的 定义 很 简单 ， 如 下 所 示 。 





typedef void (*ngx connection handler pt) (ngx connection t *c); 
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它 接收 一 个 ngx_connection t 连 接 参数 。 许 多 事件 消费 模块 〈 如 HTTP 框 架 、mail 框 娘 ) 都 
会 自 定 义 上 面 的 handler 方 法 。 











8.3.2 ”ngx_cycle t 结 构 体 


Nginx 框 架 是 围绕 着 ngx_cycle t 结 构 体 来 控制 进程 运行 的 。ngx_cycle_t 结 构 体 的 prefix、 
conf prefix、conf file 等 字符 串 类 型 成 员 保 存 着 Nginx 配 置 文件 的 路 径 ， 从 8.2 市 已 经 知道 ， 
Nginx 的 可 配置 性 完全 依赖 于 nginx.conf 恕 置 文件 ，Nginx 所 有 模块 的 可 定制 性 、 可 伸缩 性 等 诸 
多 特性 也 是 依赖 于 nginx.conf 配 置 文件 的 ， 可 以 想见 ， 这 个 配置 文件 路 径 必 然 是 保存 在 
ngx_cycle {t 结 构 体 中 的 。 





有 了 配置 文件 后 ，Nginx 框 架 就 开始 根据 配置 项 来 加 载 所 有 的 模块 了 ， 这 一 步骤 会 在 
ngx init_ cycle 方法 中 进行 〈 见 8.3.3 节 ) 。ngx init cycle 方 法， 顾名思义 ， 就 是 用 来 构造 
ngx_cycle_t 结 构 体 中 成 员 的 ， 首 先 来 介绍 一 下 ngx_cycle_t 中 的 成 员 (对 于 下 面 提 到 的 
connections、read events、write events、files、free_connections 等 成 员 ， 它 们 是 与 事件 模块 强 


相关 的 ， 本 章 将 不 做 详细 介绍 ， 在 第 9 章 中 会 详 述 这 些 成 员 的 意义 ) 。 














typedef struct ngx cycle s ngx Cycle t; struct ngx Cycle s { 





/* 保 存 着 所 有 模块 存储 配置 项 的 结构 体 的 指针 ， 它 首先 是 一 个 数组 ， 每 个 数组 成 员 又 是 一 个 指针 ， 这 个 指针 指向 另 一 个 存储 着 指针 的 数组 ， 因 





VOlid*** 大 大 */ 
void ****xconf ctx; 


// 内 存 池 


ngx Pool 七 *pool; 
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ngx_ 1og 七 日 志 对 象 的 功能 ， 这 里 的 
log 实 际 上 是 在 还 没有 执行 
ngx_init_ cycle 方法 前 ， 也 就 是 还 没有 解析 配置 前 ， 如 果 有 信息 需要 输出 到 日 志 ， 就 会 暂时 使 用 
1og 对 象 ， 它 会 输出 到 屏幕 。 在 
ngx_ init cycle 方法 执行 后 ， 将 会 根据 
nginx.conf 配 置 文件 中 的 配置 项 ， 构 造 出 正确 的 日 志文 件 ， 此 时 会 对 
log 重 新 赋值 
*/ 
ngx log 七 *]log; 
/* 由 
nginx.conf 配 置 文件 读 取 到 日 志文 件 路 径 后 ， 将 开始 初始 化 
error 10g 日 志文 件 ， 由 于 
log 对 象 还 在 用 于 输出 日 志 到 屏幕 ， 这 时 会 用 
new_1l0og 对 象 暂时 性 地 替代 
10g 日 志 ， 待 初始 化 成 功 后 ， 会 用 
new_1og 的 地 址 履 盖 上 面 的 
log 指 针 
*/ 
ngx log t new log; 


// 与 下 面 的 
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files 成 员 配 合 使 用 ， 指 出 


files 数 组 里 元 素 的 总 数 


ngx uint t files n; 


/* 对 于 


poll、 


rtsig 这 样 的 事件 模块 ， 会 以 有 效 文件 句 枉 数 来 预先 建立 这 些 


ngx_ connection 七 结构 体 ， 以 加 速 事件 的 收集 、 分 发 。 这 时 





files 就 会 保存 所 有 
ngx_connection 七 的 指针 组 成 的 数组 ， 
files_n 就 是 指针 的 总 数 ， 而 文件 句柄 的 值 用 来 访问 
files 数 组 成 员 
*y 
ngx connection 七 **files; 
// 可 用 连接 池 ， 与 


free_connection Dn 配 合 使 用 


ngx connection 七 *free connections; // 可 用 连接 池 中 连接 的 总 数 


ngx uint t free connection n; 


仔 守 和 FEF 和 站 站 所 站， http:/ /ww | 1 nNuxporobe. con 





ngx_connection 七 结构 体 ， 表 示 可 重复 使 用 连接 队列 





Ry 


ngx queue 上 reusable connections queue; /* 动 态 数组 ， 每 个 数组 元 素 存 储 着 





ngx listening 成员， 表示 监听 端口 及 相关 的 参数 
*/ 
ngx array t listening; 
/* 动 态 数 组 容器 ， 它 保存 着 
Nginx 所 有 要 操作 的 目录 。 如 果 有 目录 不 存在 ， 则 会 试图 创建 ， 而 创建 目录 失败 将 会 导致 
Nginx 启 动 失败 。 例 如 ， 上 传 文件 的 临时 目录 也 在 
pathes 中 ， 如 果 没 有 权限 创建 ， 则 会 导致 
Nginx 无 法 启动 
*/ 
ngx array t pathes; 
/* 单 链表 容器 ， 元 素 类 型 是 
ngx open file 七 结构 体 ， 它 表示 
Nginx 已 经 打开 的 所 有 文件 。 事 实 上 ， 
Nginx 框 架 不 会 向 
open_ files 链 表 中 添加 文件 ， 而 是 由 对 此 感 兴趣 的 模块 向 其 中 添加 文件 路 径 名 ， 


Nginx 框 架 会 在 
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*/ 


ngx list t open files; 


ngx_shm zone 结构 体 ， 每 个 元 素 表 示 一 块 共享 内 存 ， 共 享 内 存 将 在 第 


14 章 介绍 


4 


ngx list t shared memory; 


// 当前 进程 中 所 有 连接 对 象 的 总 数 ， 与 下 面 的 


connections 成 员 配 合 使 用 


ngx uint 七 connection n; 


// 指向 当前 进程 中 的 所 有 连接 对 象 ， 与 


connection n 配 合 使 用 


ngx connection 七 *connections; 





// 指向 当前 进程 中 的 所 有 读 事件 对 象 ， 


connection n 同 时 表示 所 有 读 事件 的 总 数 


ngx event t *read events; 





// 指向 当前 进程 中 的 所 有 写 事件 对 象 ， 
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connection n 同 时 表示 所 有 写 事件 的 总 数 


ngx event t *write events; 


/* 旧 的 


ngx_cycle 七 对 象 用 于 引用 上 一 个 


ngx_cycle 七 对 象 中 的 成 员 。 例 如 


ngx init cycle 方法 ， 在 启动 初期 ， 需 要 建立 一 个 临时 的 


ngx_cycle 七 对 象 保存 一 些 变 量 ， 再 调用 


ngx_jinit_cycle 方 法 时 就 可 以 把 旧 的 


ngx_cycle 七 对 象 传 进去 ， 而 这 时 


old cycle 对象 就 会 保存 这 个 前 期 的 


ngx_cycle 上 上 对象 


4 


ngx Cycle 七 *old cycle; 





// 配置 文件 相对 于 安装 目录 的 路 径 名 称 


ngx str t conf file; 
/*Nginx 处 理 配 置 文件 时 需要 特殊 处 理 的 在 命令 行 携带 的 参数 ， 一 般 是 
-g 选 项 携带 的 参数 


G4 


科 = 站 [和 和 站 Ptto:/ ww inuxorobe. con 





// Nginx 配 置 文件 所 在 目录 的 路 径 


ngx_ str t conf prefix; 


// Nginx 安 装 目 录 的 路 径 


ngx str t prefix; 


// 用 于 进程 间 同 步 的 文件 锁 名 称 


ngx str t lock file; 


// 使 用 


gethostname 系 统 调 用 得 到 的 主机 名 


ngx_ str t hostname; 





在 构造 negx cycle it 结构 体 成 员 的 ngx init cycle 方 法 中 ， 上 面 所 列 出 的 pool 内 存 池 成 员 、 
hostname 主 机 名 、 日 志文 件 new_ log 和 log、 存 储 所 有 路 径 的 pathes 数 组 、 共 享 内 存 、 监 听 端 口 
等 都 会 在 该 方法 中 初始 化 。 本 章 后 续 提 到 的 流程 、 方 法 中 可 以 随处 见 到 ngx_cycle t 结 构 体 成 


员 的 身影 。 
8.3.3 ”ngx_cycle {支持 的 方法 
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与 ngx_cycle _t 核 心 结构 体 相 关 的 方法 实际 上 是 非常 多 的 。 例 如 ， 每 个 模块 都 可 以 通过 
init module、init process、exit process、exit master 等 方法 操作 进程 中 独 有 的 ngx_cycle t 结 构 
体 。 然 而 ，Nginx 的 框架 代码 中 关于 ngx_cycle t 结 构 体 的 方法 并 不 是 太 多 ， 表 8-2 中 列 出 了 与 
ngx_cycle t 相 关 的 主要 方法 ， 我 们 先 做 一 个 初步 的 介绍 ， 在 后 面 的 章节 中 将 会 提 到 这 些 方法 
的 意义 。 


表 8-2 中 列 出 的 许多 方法 都 可 以 在 下 面 各 节 中 找到 。 例 如 ，ngx_init_cycle 方 法 的 流程 可 参 
照 图 8-6 中 的 第 3 步 〈 调 用 所 有 核心 模块 的 create_conf 方 法 ) ~ 第 8 步 〈 调 用 所 有 模块 的 
init module 方 法 ) 之 间 的 内 容 ; ngx worker process_cycle 方 法 可 部 分 参照 图 8-7〈 图 8-7 中 缺 
少 调用 ngx worker process init 方 法 ) ; ngx master process_cycle 监 控 、 管 理子 进程 的 流程 可 
参照 图 8-8。 


表 8-2 ngx_cycle_t 结 构 体 支持 的 主要 方法 
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方法 名 


ngX_cycle t *ngx init cycle 
(ngx_ cycle t *old cycle) 


ngx int t ngx process options 
(ngx cycle t *cycle) 


ngx_int t ngx add inherited 
sockets(ngx cycle t *cycle) 


ngx_int t ngx open listening_ 
sockets (ngx _ cycle t *cycle) 

void ngx configure listening_ 
sockets(ngx cycle t *cycle) 

void ngx close listening_ 

sockets(ngx cycle t *cycle) 

void ngx master process __ 

cycle(nex cycle t *cycle) 

void ngx single process cycle 
(ngx cycle t *cycle) 


void ngx start worker 
processes (ngx cycle t *cycle, 
ngx_int tn, ngx int t type) 


old_cycle 表示 临时 的 ngx_cycle t 指 
针 ， 一般 仅 用 来 传递 ngx_cycle t 结 构 
体 中 的 配置 文件 路 径 等 参数 


cycle 通常 是 刚刚 分 配 的 ngx_cycle t 结 构 
体 指针 ， 仅 用 于 传递 配置 文件 路 径 信息 


cycle 是 当前 进程 的 ngx_cycle {t 结 构 
体 指 针 


cycle 是 当前 进程 的 ngx_cycle t 结构 
体 指针 


cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 


cycle 是 当前 进程 的 ngx_cycle 1 结构 
体 指针 

cycle 是 当前 进程 的 ngx_cycle 1 结构 
体 指 针 

cycle 是 当前 进程 的 ngx_cycle 【结构 
体 指 针 

cycle 是 当前 进程 的 ngx_cycle 1 结构 
体 指针 , n 是 启动 子 进程 的 个 数 ，type 
是 启动 方式 ， 它 的 取 值 范围 有 以 下 5 个 : 

1 ) NGX PROCESS RESPAWN:; 

2) NGX PROCESS NORESPAWN; 

3 ) NGX PROCESS JUST SPAWN:; 

4 ) NGX_PROCESS JUST RESPAWN:; 

5) NGX PROCESS DETACHED. 
type 的 值 将 影响 8.6 节 中 ngx_process t 结 
构 体 的 respawn、detached、just_ spawn 标 
志 位 的 值 





执行 意义 

返回 初始 化 成 功 的 完整 的 ngx_eycle_ 
t 结构 体 ， 该 函数 将 会 负责 初始 化 ngx_ 
cycle t 中 的 数据 结构 、 解 析 配 置 文件 、 
加 载 所 有 模块 、 打 开 监听 端口 、 初 始 化 
进程 间 通 信 方 式 等 工作 。 如 果 失 败 ， 则 
返回 NULL 空 指 针 

用 运行 Nginx 时 可 能 携带 的 目录 参数 
来 初始 化 cycle， 包 括 初 始 化 运行 目录 ， 
配置 目录 ， 并 生成 完整 的 nginx.conf 配 
前 文件 路 径 

在 执行 不 重启 服务 升级 Nginx 的 操作 
时 ， 老 的 Nginx 进程 会 通过 环境 变量 
“NGINX ”来 传递 需要 打开 的 监听 端 
口 ， 新 的 Nginx 进程 会 通过 ngx add_ 
inherited_sockets 方法 来 使 用 已 经 打开 
的 TCP 监听 端口 

监听 、 绑 定 cycle 中 listening 动态 数 
组 指定 的 相应 端口 

根据 nginx.conf 中 的 配置 项 设置 已 经 
监听 的 句柄 

关闭 cycle 中 listening 动态 数组 已 经 
打开 的 句柄 


进入 master 进程 的 工作 循环 


进入 单 进程 模式 ( 非 master、worker 
进程 工作 模式 ) 的 工作 循环 


启动 n 个 worker 子 进程 ， 并 设置 好 
每 个 子 进 程 与 master 父 进 程 之 间 使 用 
socketpair 系统 调用 建立 起 来 的 socket 
句柄 通信 机 制 
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方法 名 


cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 ,respawn 是 启动 子 进程 的 方式 ， 
它 与 ngx_start worker_processes 方法 中 
的 type 参数 意义 完全 相同 


void ngx_start cache _ 
manager processes(ngx cycle t 


*cycle, ngx_uint t respawn) 


void ngx_ pass_ open channel cycle 是 当前 进程 的 ngx_cycle 结构 


体 指针 ，ch 是 将 要 问 子 进程 发 送 的 信息 


(NEX Cyele t eycle, Wer 
channel t *ch) 

cycle 是 当前 进程 的 ngx_cycle t 结构 
体 指针 ，signo 是 信号 


void ngx_signal worker processes 
(ngx_ cycle t *cycle, int Signo) 


cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 


ngx uint t ngx reap children 
(ngx_ cycle t *cycle) 
cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 

cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 ， 这 里 还 未 开始 使 用 data 参数 ， 
所 以 data 一 般 为 NULL 


voidngx master process exit 
(ngx cycle t *cycle) 


void ngx worker process cycle 
(ngx_ cycle t *cycle, void *data) 


cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指 针 ，priority 是 worker 进程 的 系统 
优先 级 


void ngx_ worker process init 
(ngx_ cycle t *cycle, ngx uint t 
priority) 

cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指 针 

cycle 是 当前 进程 的 ngx cycle t 结 
构 体 指针 ，data 是 传人 的 ngx_cache_ 
manager_ctx_t 结构 体 指针 


void ngx worker process exit 
(ngx cycle t *cycle) 

void ngx cache manager_ 
process cycle(nex cycle t *cycle, 
void *data) 
cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指 针 


void ngx process events and 
timers (ngx_cycle t *cycle) 





( 续 ) 
执行 意义 
根据 是 否 使 用 文件 缓存 模块 ， 也 就 是 
cycle 中 存储 路 径 的 动态 数组 中 是 否 有 路 
径 的 manage 标志 打开 ， 来 决定 是 否 启 动 
cache manage 子 进 程 ， 同样 根据 loader 


标志 决定 是 否 启动 cache loader 子 进程 
回 所 有 已 经 打开 的 channel{( 通 过 


socketpair 生成 的 句柄 进行 通信 ) 发 送 
ch 信息 


处 理 worker 进程 接收 到 的 信号 


检查 master 进程 的 所 有 子 进 程 ， 根 
据 每 个 子 进程 的 状态 (ngx_process t 结 
构 体 中 的 标志 位 ) 判断 是 否 要 启动 子 进 
程 、 更 改 pid 文件 等 


退出 master 进程 工作 的 循环 


进入 worker 进程 工作 的 循环 


进入 worker 进程 工作 循环 之 前 的 初 
始 化 工作 


退出 worker 进程 工作 的 循环 


执行 缓存 管理 工作 的 循环 方法 。 这 与 
文件 缓存 模块 密切 相关 ， 在 本 章 中 不 做 
详细 探讨 

使 用 事件 模块 处 理 截止 到 现在 已 经 收 
集 到 的 事件 。 该 号 数 由 事件 模块 实现 ， 
详 见 第 9 章 
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8.4 ”Nginx 司 动 时 框架 的 处 理 流程 


通过 阅读 8.3 市 ， 读 者 应 该 对 ngx_cycle 结构 体 有 了 基本 的 了 解 ， 下 面 继续 介绍 Nginx 在 
局 动 时 框架 做 了 些 什么 。 注 意 ， 本 节 描 述 的 Nginx 启 动 流 程 基本 上 不 包含 Nginx 模 块 在 启动 流 
程 中 所 做 的 工作 ， 仅 仅 是 展示 框架 代 码 如 何 使 服务 运行 起 来 ， 这 里 的 框架 主要 束 是 调用 表 8- 
2 中 列 出 的 方法 。 





如 图 8-6 所 示 ， 这 里 包括 Nginx 框 架 在 启动 阶段 执行 的 所 有 基本 流程 ， 零 碎 的 工作 这 里 不 
涉及 ， 对 一 些 复杂 的 业务 也 仅 做 简单 说 明 (如 图 8-6 中 的 第 2 步 涉及 的 平滑 升级 的 问题 ) ， 本 
节 关 注 的 重点 只 是 Nginx 的 正常 启动 流程 。 


TiNNinNnn http://wWwWw linuxorobe.con 





1 ) 根 据 命令 行 得 到 
配置 文件 路 径 


2 ) 如 果 处 于 升级 中 ， 则 监听 环境 
变量 里 传递 的 监听 句柄 










3 ) 调用 所 有 核心 模块 的 create_conf 方法 
生成 存放 配置 项 的 结构 体 


4) 针对 所 有 核心 7 


nginx conf 配置 文 


5) 调用 所 有 核心 模块 的 


init _conf 方 法 


6 ) 创 建 目录 、 打 开 文 件 、 初 始 化 共享 
内 存 等 进程 间 通信 方式 


7) 打 开 由 各 Nginx 模块 从 配置 文件 
中 读 取 到 的 监听 端口 


8) 调用 所 有 模块 的 
init _module 方 法 


[检测 Nginx 运 行 方式 ] 
[以 单 进程 方式 运行 Nginx] 
















9) 进 入 single 模式 





了 

一 
7 

(ma 
只 


[以 master 多 进程 方式 运行 Nginx ] 









进入 master 模 式 i 
10) 调用 所 有 模块 的 init_process 方 法 
[多 进程 并 发 执行 ] 












11 ) master 进程 


14) 启动 cache manager 进 程 12 ) 启动 worker 进 程 





15 ) 启动 cache loader 子 进程 ) (13) 调用 所 有 模块 的 init_process 方 法 





16) 关闭 父 进程 启动 时 
监听 的 端口 


8-0 
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下 面 简 要 介绍 一 下 图 8-6 中 的 主要 步骤: 


1) 在 Nginx 有 启动 时 ， 首 先 会 解析 命令 行 ， 处 理 各 种 参数 。 因 为 Nginx 是 以 配置 文件 作为 
核心 提供 服务 的 ， 所 以 最 主要 的 就 是 确定 配置 文件 nginx.conf 的 路 径 。 这 里 会 预先 创建 一 个 临 
时 的 ngx_cycle_t 类 型 变量 ， 用 它 的 成 员 存 储 配置 文件 路 径 〈 实 际 上 还 会 使 用 这 个 临时 
ngx_cycle t 结 构 体 的 其 他 成 员 ， 如 log 成 员 会 指 问 屏 玫 输 出 日 志 ) ， 最 后 调用 表 8-2 中 的 
ngx_process_options 方 法 来 设置 配置 文件 路 径 等 参数 。 


2) 网 8-6 中 的 第 2 步 实际 上 就 是 在 调用 表 8-2 中 的 ngx_add_inherited_sockets 方 法 。Nginx 在 
不 重启 服务 升级 时 ， 也 就 是 我 们 说 过 的 平滑 升级 《参见 1.9 节 ) 时 ， 它 会 不 重启 master 进 程 而 
启动 新 版 本 的 Nginx 程 序 。 这 样 ， 旧 版 本 的 master 进 程 会 通过 execve 系 统 调用 来 启动 新 版 本 的 
master 进 程 〈 先 fork 出 子 进程 再 调用 exec 来 运行 新 程序 ) ， 这 时 旧版 本 的 master 进 程 必须 要 通 
过 一 种 方式 告诉 新 版 本 的 master 进 程 这 是 在 平滑 升级 ， 并 且 传 递 一 些 必要 的 信息 。Nginx 是 通 
过 环境 变量 来 传递 这 些 信 息 的 ， 新 版 本 的 master 进 程 通 过 ngx add inherited sockets 方 法 由 环 
境 变 量 里 读 取 平 滑 升级 信息 ， 并 对 旧版 本 Nginx 服 务 监听 的 句柄 做 继承 处 理 。 














3) 第 3 步 ~ 第 8 步 ， 都 是 在 ngx_init_cycle 方 法 中 执行 的 。 在 初始 化 ngx_cycle_t 中 的 所 有 容 
器 后 ， 会 为 读 取 、 解 析 配 置 文件 做 准备 工作 。 因 为 每 个 模块 都 必须 有 相应 的 数据 结构 来 存储 
配置 文件 中 的 各 配置 项 ， 创 建 这 些 数据 结构 的 工作 都 需要 在 这 一 步 进 行 。Nginx 框 架 只 关心 
NGX_ CORE MODULE 核 心 模块 ， 这 也 是 为 了 降低 框架 的 复杂 度 。 这 里 将 会 调用 所 有 核心 模 
块 的 create_conf 方 法 (也 只 有 核心 模块 才 有 这 个 方法 ) ， 这 意味 着 需要 所 有 的 核心 模块 开始 
构造 用 于 存储 配置 项 的 结构 体 。 其 他 非 核心 模块 怎么 办 呢 ? 其 实 很 简单 。 这 些 模块 大 都 从 属 
于 一 个 核心 模块 ， 如 每 个 HTTP 模 块 都 由 ngx http module 管理 〈 如 图 8-2 所 示 ) ， 这 样 
ngx_http_module 在 解析 自己 感 兴趣 的 “http”* 配 置 项 时 ， 将 会 调用 所 有 HTTP 模 块 约定 的 方法 来 
创建 存储 配置 项 的 结构 体 〈( 如 第 4 章 中 介绍 过 的 xxx_create_main conf、xxx create_srv_conf、 

















XXX create loc conf 方 法 ) 。 


人 人才 一人 





配置 项 ， 将 会 检查 所 有 核心 模块 以 找 出 对 它 感 兴趣 的 模块 ， 并 调用 该 模块 在 ngx_command t 
结构 体 中 定义 的 配置 项 处 理 方法 。 这 个 流程 可 以 参考 图 4-1。 


5) 调用 所 有 NGX_CORE _ MODULE 核心 模块 的 init_ conf 方 法 。 这 一 步骤 的 目的 在 于 让 上 所 
有 核心 模块 在 解析 完 配 置 项 后 可 以 做 综合 性 处 理 。 


6) 在 之 前 核心 模块 的 init_conf 或 者 create_conf 方 法 中 ， 可 能 已 经 有 些 模 块 〈 如 缓存 模 
块 ) 在 ngx_cycle t 结 构 体 中 的 pathes 动 态 数 组 和 open files 链 表 中 添加 了 需要 打开 的 文件 或 者 
目录 ， 本 步 又 将 会 创建 不 存在 的 目录 ， 并 把 相应 的 文件 打开 。 同 时 ，ngx_cycle_t 结 构 体 的 
shared_memory 链 表 中 将 会 开始 初始 化 用 于 进程 间 通 信 的 共 孕 内存。 





7) 之 前 第 4 步 在 解析 配置 项 时 ， 所 有 的 模块 都 已 经 解析 出 目 己 需要 监听 的 端口 ， 如 
HTTP 模 块 已 经 在 解析 http{...} 配 置 项 时 得 到 它 要 监听 的 端口 ， 并 添加 a 到 listening 数 组 中 了 。 这 
一 步 又 就 是 按照 listening 数 组 中 的 每 一 个 nex listening {t 元 素 设 置 socket 句 柄 并 监听 端口 〈 实 际 
上 ， 这 一 步骤 的 主要 工作 就 是 调用 表 8-2 中 的 ngx_ open listening sockets 方 法 ) 。 


8) 在 这 个 阶段 将 会 调用 所 有 模块 的 init module 方 法 。 接 下 来 将 会 根据 配置 的 Nginx 运 行 
模式 决定 如 何 工作 。 


9) 如 果 nginx.conf 中 配置 为 单 进程 工作 模式 ， 这 时 将 会 调用 ngx single process_ cycle 方法 
进入 单 进程 工作 模式 。 


10) 调用 所 有 模块 的 init_process 方 法 。 单 进程 工作 模式 的 启动 工作 至 此 全 部 完成 ， 将 进 
入 正常 的 工作 模式 ， 也 融 是 8.$ 节 和 8.6 节 分 别 介 绍 的 worker 进 程 工 作 循环 、master 进 程 工作 循 
环 的 结合 体 。 





11) 如 果 进 入 master、worker 工 作 模式 ， 在 启动 worker 子 进程 、cache manage 子 进程 、 
cache loader 子 进程 后 ， 束 开始 进入 8.6 节 提 到 的 工作 状态 ， 人 至 此 ，master 进 程 启动 流程 执行 完 


毕 。 
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12〉 由 master 进 程 按照 配置 文件 中 worker 进 程 的 数目 ， 启 动 这 些 子 进程 (也 就 是 调用 表 
8-2 中 的 ngx start worker processes 方 法 ) 。 





13) 调用 所 有 模块 的 init process 方 法 。worker 进 程 的 启动 工作 至 此 全 部 完成 ， 接 下 来 将 
进入 正 第 的 循环 处 理事 件 流程 ， 也 就 是 8.5 节 中 介绍 的 worker 进 程 工作 循环 的 
ngx Worker process_cycle 方 法 。 





14) 在 这 一 步 又 中 ， 由 master 进 程 根据 之 前 各 模块 的 初始 化 情况 来 决定 是 否 局 动 cache 
manage 子 进程 ， 也 就 是 根据 ngx_cycle_t 中 存储 路 径 的 动态 数组 pathes 中 是 否 有 某 个 路 径 的 
manage 标 志 位 打开 来 决定 是 否 启 动 cache manage 子 进程 。 如 果 有 任何 1 个 路 径 的 manage 标 志 位 
为 1， 则 启动 cache manage 子 进程 。 








15) 与 第 14 步 相同 ， 如 果 有 任何 1 个 路 径 的 loader 标 志 位 为 1， 则 启动 cache loader 子 进 
程 。 对 于 第 14 步 和 第 1$ 步 而 言 ， 都 是 与 文件 缓存 模块 密切 相关 的 ， 但 本 章 不 会 详 述 。 





16) 关闭 只 有 worker 进 程 才 需 要 监听 的 端口 。 


在 以 上 16 个 步骤 中 ， 简 要 地 列举 出 了 Nginx 在 单 进程 模式 和 master 工 作 方式 下 的 启动 流 
程 ， 这 里 仅 列 举 出 与 Nginx 框 架 密 切 相 关 的 步骤 ， 并 未 涉及 具体 的 模块 。 
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8.5 ”worker 进 程 是 如 何 工 作 的 


本 市 的 内 容 不 会 涉及 事件 模块 的 处 理工 作 ， 只 是 探讨 在 worker 进 程 中 循环 执行 的 
ngx_ Worker_process_cycle 方 法 是 如 何 控制 进程 运行 的 。 





master 进 程 如 何 通 知 worker 进 程 停止 服务 或 更 换 日 志文 件 呢 ?对 于 这 样 控 制 进程 运行 的 
进程 间 通 信 方 式 ，Nginx 采 用 的 是 信号 〈 详 见 14.5 节 ) 。 因 此 ，worker 进 程 中 会 有 一 个 方法 来 
处 理 信 号 ， 它 就 是 ngx signal handler 方 法 。 





void ngx _ signal handler (int signo) 





对 于 worker 进 程 的 工作 方法 ngx worker process_cycle 来 说 ， 它 会 关注 以 下 4 个 全 局 标志 





sig atomic t ngx terminate; 
sig atomic t ngx quit; 

ngx uint t ngx exiting; 
sig atomic t ngx reopen; 














其 中 的 ngx terminate、ngx quit、ngx reopen 都 将 由 ngx signal handler 方 法 根据 接收 到 的 信 
号 来 设置 。 例 如 ， 当 接收 到 QUIT 信 号 时 ，ngx _ quit 标 志 位 会 设 为 1!， 这 是 在 告诉 worker 进 程 需 
要 优雅 地 关闭 进程 ， 当 接收 到 TERM 信号 时 ，ngx_terminate 标 志 位 会 设 为 1， 这 是 在 告诉 
worker 进 程 需要 强制 关闭 进程 ， 当 接收 到 USR1 信 号 时 ，ngx reopen 标 志 位 会 设 为 1， 这 是 在 
告诉 Nginx 需 要 重新 打开 文件 〈 如 切换 日 志文 件 时 ) ， 见 表 8-3。 


表 8-3 worker 进 程 接收 到 的 信号 对 框架 的 意义 





入 号 对 应 进程 中 的 全 局 标志 位 变 意 义 


TERM 或 才 INT 强制 关闭 进 和 
Um ee 


WINCH ngx_debphg, quit ， ”日 前 没有 实际 意义 
J, 


pe 症状 亲 = 国 亲 王国 国 ea 本 省 = 全 辐 a | 本 本 = s 
VWWYV 人 信人 UA 人 





ngx_exiting 标 志 位 仅 由 ngx _ worker process_cycle 方 法 在 退出 时 作为 标志 位 使 用 ， 如 图 8-7 
所 示 。 
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[ngxexiting 标 志 位 为 1, 进程 退出 ] 








对 当前 所 有 活动 连接 调用 读 事 件 
方法 处 理 关 闭 连接 事件 





[还 有 未 处 理 完 的 事件 ] 





检查 并 分 发 、 
处 理事 件 


<> 


[所 有 连接 都 已 关闭 ] 


、 LILeT In ’ 未 志 71> ls 强 训 结 进 3 、 一 HH 
i ee 志 位 为 1, 强制 结束 进程 调用 所 有 模块 的 
exit_proces 坊 法 










[ngx_terminate 为 0] 


[ngx_quit 标 志 位 为 1 ,优雅 地 关闭 进程 ] 


[ngx_ uit 为 0] 关闭 所 有 监听 句柄 并 设置 


ngx_exlting 隶 标志 





内 存 池 


[ngx_reopen 标志 位 为 1, 重新 打开 所 有 文件 ] 


二 





重新 打开 
所 有 文件 


图 8-7 worker 进 程 正常 工作 、 退 出 时 的 流程 图 


在 ngx worker_ process_cycle 方 法 中 ， 通 过 检查 ngx_exiting、ngx_terminate、ngx_quit、 
ngx_reopen 这 4 个 标志 位 来 决定 后 续 动 作 。 


如 果 ngx_exiting 为 1， 则 开始 准备 关闭 worker 进 程 。 首 先 ， 根 据 当 前 ngx_cycle_t 中 所 有 正 
在 处 理 的 连接 ， 调 用 它们 对 应 的 关闭 连接 处 理 方法 “就 是 将 连接 中 的 close 标 志 位 置 为 1， 再 
调用 读 事 件 的 处 理 方法 ， 在 第 9 章 中 会 详细 讲解 Nginx 连 接 ) 。 调 用 所 有 活动 连接 的 读 事件 处 
理 方法 处 理 连 接 关 闭 事件 后 ， 将 检查 ngx_event timer_rbtree 红 黑 树 (保存 所 有 事件 的 定时 
器 ， 在 第 9 章 中 会 介绍 它 ) 是 否 为 空 ， 如 果 不 为 空 ， 表 示 还 有 事件 需要 处 理 ， 将 继续 癌 下 执 


行 ， 调 用 ngx process_events and timers 方 法 处 理事 件 ; 如 来 为 空 ， 表示 已 经 处 理 完 所 有 的 事 
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件 ， 这 时 将 调用 所 有 模块 的 exit process 方 法 ， 最 后 销毁 内 存 池 ， 退 出 整个 worker 进 程 。 


@ 注意 ”ngx_exiting 标 志 位 只 有 唯一 一 段 代码 会 设置 它 ， 也 就 是 下 面 接收 到 QUIT 信 


号 。ngx_quit 只 有 在 首次 设置 为 1 时 ， 才 会 将 ngx_exiting 置 为 1。 


如 果 ngx exiting 不 为 1， 那 么 调用 ngx process_ events and timers 方 法 处 理事 件 。 这 个 方法 


是 事件 模块 的 核心 方法 ， 将 会 在 第 9 章 介 绍 它 。 


接 下 来 检查 ngx terminate 标 志 位 ， 如 果 nex terminate 不 为 1， 则 继续 向 下 检查 ， 否 则 开始 
准备 退出 worker 进 程 。 与 上 一 步 ngx_exiting 为 1 的 退出 流程 不 同 ， 这 里 不 会 调用 所 有 活动 连接 
的 处 理 方 法 去 处 理 关 闭 连接 事件 ， 也 不 会 检查 是 否 已 经 处 理 完 所 有 的 事件 ， 而 是 立刻 调用 所 
有 模块 的 exit process 方 法 ， 销 毁 内 存 池 ， 退 出 worker 进 程 。 











接 下 来 再 检查 ngx_quit 标 志 位 ， 如 果 标 志 位 为 1， 则 表示 需要 优雅 地 关闭 连接 。 这 时 ， 
Nginx 首 先 会 将 所 在 进程 的 名 字 修 改 为 “worker process is shutting down”， 然 后 调用 
ngx close listening sockets 方 法 来 关闭 监听 的 端口 ， 接 着 设置 ngx exiting 标 志 位 为 1， 继 续 问 
下 执行 (检查 ngx reopen files 标志 位 ) 。 


最 后 检查 ngx reopen 标 志 位 ， 如 果 为 1， 则 表示 需要 重新 打开 所 有 文件 。 这 时 ， 调 用 
ngx_ reopen _ files 方法 重新 打开 所 有 文件 。 之 后 继续 下 一 个 循环 ， 再 去 检查 ngx_exiting 标 志 


位 。 
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8.6 master 进程 是 如 何 工 作 的 


master 进 程 不 需要 处 理 网 络 事件 ， 它 不 负责 业务 的 执行 ， 只 会 通过 管理 worker 等 子 进程 
来 实现 重 局 服务 、 平 滑 升 级 、 更 换 日 志文 件 、 配 置 文件 实时 生效 等 功能 。 与 8.5 节 类 似 的 
是 ， 它 会 通过 检查 以 下 7 个 标志 位 来 决定 ngx_master_process_cycle 方 法 的 运行 。 








sig atomic 
sig atomic 
sig atomic 
sig atomic 
sig atomic 
sig atomic 
sig atomic 


ngx reap; 
ngx terminate; 

ngx quit; 

ngx reconfigure; 
ngx reopen; 

ngx change binary; 
ngx noaccept; 




















et 








ngx_signal_handler 方 法 会 根据 接收 到 的 信号 设置 ngx_ reap、ngx_quit、ngx_terminate、 


ngx reconfigure、ngx reopen、ngx change binary、ngx noaccept 这 些 标 志 位 ， 见 表 8-4。 


表 8-4 进程 中 接收 到 的 信号 对 Nginx 框 架 的 意义 


信 号 对 应 进程 中 的 意 义 
全 局 标志 位 变量 
QUIT ngx quit 优雅 地 关闭 整个 服务 
TERM 或 者 INT ngx terminate 强制 关闭 整个 服务 
USR1 ngx reopen 重新 打开 服务 中 的 所 有 文件 


所 有 子 进 程 不 再 接受 处 理 新 的 连接 ， 实 际 相 当 于 对 所 有 的 子 进程 
发 送 QUIT 信号 量 
USR2 ngx_ change_binary 平滑 升级 到 新 版 本 的 Nginx 程序 
HUP ngx reconfigure 重读 配置 文件 并 使 服务 对 新 配置 项 生效 

有 子 进程 意外 结束 ， 这 时 需要 监控 所 有 的 子 进 程 ， 也 就 是 ngx 
reap_children 方法 所 做 的 工作 


WINCH ngx noaccept 


SHLD ngx reap 


人 0 吗 0 人 
| | 1 | | 
全 , 
ga | 





表 8-4 列 出 了 master 工 作 流 程 中 的 7 个 全 局 标志 位 变量 。 除 此 之 外 ， 还 有 一 个 标志 位 也 会 
用 到 ， 它 仅仅 是 在 master 工 作 流 程 中 作为 标志 位 使 用 的 ， 与 信号 无 关 。 





ngx uint t ngx restart; 
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在 解释 master 工 作 流 程 前 ， 还 需要 对 master 进 程 管理 子 进程 的 数据 结构 有 个 初步 了 解 。 
下 面 定 义 了 ngx processes 全 局 数组 ， 虽 然 子 进程 中 也 会 有 ngx_processes 数 组 ， 但 这 个 数组 仅 
仅 是 给 master 进 程 使 用 的 。 下 面 看 一 下 ngx processes 全 局 数组 的 定义 ， 代 码 如 下 。 





/十 头 
1024 个 元 素 的 


ngx processes 数 组 ， 也 就 是 最 多 只 能 有 


1024 个 子 进程 





#define NGX MAX PROCESSES 1024 
// 当前 操作 的 进程 在 











ngx processes 数 组 中 的 下 标 


ngx int t ngx process slot; 
// ngx processes 数 组 中 有 意义 的 


ngx_process 七 元 素 中 最 大 的 下 标 


ngx int t ngx last process; 


// 存储 所 有 子 进程 的 数组 

















ngx process t ngx processes[NGX MAX PROCESSES]; 





master 进 程 中 所 有 子 进程 相关 的 状态 信息 都 保存 在 ngx processes 数 组 中 。 再 来 看 一 下 数 
组 元 素 的 类 型 ngx process t 结 构 体 的 定义 ， 代 码 如 下 。 





typedef struct { 
// 进程 


ID 
ngx pid t pid; 
// 由 


waitpid 系 统 调用 获取 到 的 进程 状态 


int status; 
/* 这 是 由 
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socketpair 系 统 调 用 产生 出 的 用 于 进程 间 通 信 的 


socket 和 句柄， 这 一 对 


socket 句柄 可 以 互相 通信 ， 目 前 用 于 


master 父 进程 与 





worker 子 进程 间 的 通信 ， 详 见 


14.4 节 


A 
ngx socket t channel[2]; 


// 子 进 程 的 循环 执行 方法 ， 当 父 进 程 调用 


ngx_Sspawn_ process 生 成 子 进 程 时 使 用 


ngx_ spawn proc pt proc; 


/* 上 面 的 


ngx spawn proc pt 方法 中 第 


2 个 参数 需要 传递 


1 个 指针 ， 它 是 可 选 的 。 例 如 ， 


worker 子 进程 就 不 需要 ， 而 


cache manage 进 程 就 需要 


ngx cache manager ctx 上 下 文成 员 。 这 时 ， 


data 一 般 与 


ngx_ spawn proc pt 方法 中 第 


2 个 参数 是 等 价 的 
交 

void data; 

// 进程 名 称 。 操 作 系 统 中 显示 的 进程 名 称 与 
name 相 同 


char *name; 


// 标志 位 ， 为 


1 时 表示 在 重新 生成 子 进程 
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unsigned respawn:1; 


// 标志 位 ， 为 


1 时 表示 正在 生成 子 进 程 


unsigned just spawn:1; 


// 标志 位 ， 为 


1 时 表示 在 进行 父 、 子 进程 分 离 


unsigned detached:1; 


// 标志 位 ， 为 


1 时 表示 进程 正在 退出 


unsigned exiting:1; 


// 标志 位 ， 为 


1 时 表示 进程 已 经 退出 


unsigned exited:1; 
} ngx process t; 





master 进 程 怎 样 启 动 一 个 子 进程 呢 ? 其 实 很 简单 ，fork 系 统 调用 即 可 以 完成 。 
ngx spawn process 方 法 封装 了 fork 系 统 调 用 ， 并 且 会 从 ngx processes 数 组 中 选择 一 个 还 未 使 
用 的 ngx_process_t7E 素 存储 这 个 子 进程 的 相关 信息 。 如 果 所 有 1024 个 数组 元 素 中 已 经 没有 空 
余 的 元 系 ， 也 融 是 说 ， 子 进程 个 数 超过 了 最 大 值 1024， 那 么 将 会 返回 NGX_JINVALID_PID。 
因此 ，ngx_processes 数 组 中 元 素 的 初始 化 将 在 ngx_spawn_process 方 法 中 进行 。 





下 面 对 局 动 子 进程 的 方法 做 一 个 简单 说 明 ， 它 的 定义 如 下 。 





ngx pid t ngx spawn process(ngx cycle t *cycle, ngx spawn proc pt proc, void data, char name, ngx int t respawn 











这 里 的 proc 函 数 指针 就 是 子 进程 中 将 要 执行 的 工作 循环 。 下 面 看 一 下 ngx_spawn proc_pt 
的 定义 ， 代 码 如 下 。 





typedef void (*ngx Spawn proc pt) (ngx cycle t cycle, void data); 
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此 ，worker 进 程 的 工作 循环 ngx worker process_cycle 方 法 也 是 依照 hgx spawn proc pt 
来 定义 的 ， 代 码 如 下 。 





static void ngx worker process cycle (ngx_ cycle 七 cycle, void data); 





cache manage 进 程 或 者 cache loader 进 程 的 工作 循环 ngx cache manager process cycle 方法 
也 是 如 此 ， 代 码 如 下 。 








static void ngx cache manager process cycle(ngx cycle t cycle, void data); 








那么 ，ngx_processes 数 组 中 这 些 进 程 的 状态 是 怎么 改变 的 呢 ? 依靠 信号 ! 当 每 个 子 进程 
意外 退出 时 ，master 父 进程 会 接收 到 Linux 内 核发 来 的 CHLD 信 号 ， 而 处 理 信 号 的 
ngx_signal_handler 方 法 这 时 将 会 做 以 下 处 理 ， 将 sig_reap 标 志 位 置 为 1， 调 用 
ngx_process_get_status 方 法 修改 ngx_processes 数 组 中 所 有 子 进程 的 状态 (通过 waitpid 系 统 调用 
得 到 意外 结束 的 子 进程 ID， 然 后 遍历 ngx processes 数 组 找到 该 子 进程 ID 对 应 的 ngx process { 
结构 体 ， 将 其 exited 标 志 位 置 为 1) 。 那 么 ， 一 个 子 进程 意外 结束 后 ， 如 何 启动 新 的 子 进程 
呢 ? 这 可 以 在 图 8-8 所 示 的 master 进 程 的 工作 循环 中 找到 答案 。 
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[ngx_reap 标 志 位 为 1] 
>» 1 ) 监 控 子 进程 , 若 所 有 子 进程 
> 已 退出 则 返回 的 live 为 0 


[live 标 志 位 为 0, 同时 ngx_terminate 或 者 ngx_quit 标志 位 为 1 ] 








6) 辣 所 有 子 进 程 发 这 <> 
TERM 信和 号 
[ngx terminate 标 志 位 为 1, 强制 关闭 服 A 2 te 
7) 回 J 发 送 [ngx_terminate 为 0 ] 3) 调 用 所 有 模块 的 






exit_master 方 > 





[ngx_quit 标志 位 为 1， 









优雅 地 关闭 服务 ] 4) 关 闭 所 有 
中 1 
下 有 有 有 [ngx _quit 为 0 ] 监听 端口 
监听 端口 
5) 销 毁 内 存 池 
[ngx_reconfigure 标 志 位 为 1] <> 
[ngx_reconfigure 为 0] 者 
9) 重 新 恋 取 
了 JE -ww- (证 
配置 文件 eit 1] 13) En 
worker 子 进程 
10) 局 动 worker 
进 三 去 
子 进程 [ngx_restart 为 0] 14) 启 动 cache manage 





11) 启动 cache manage 
六 1 二 


[ngx_reopen 标 志 位 为 1] 15) 重 新 





Ei 





1 向 所 有 子 进 程 发 送 
QUIT 信 号 


[ngx_reopen 为 0] 16) 向 所 大 的 子玉 各 发 这 
USR1 信 号 要 求 重 新 打开 文件 
[ngx_change _binary 标 志 位 为 1] 


17) 运行 新 的 Nginx 








二 进 制 文件 


[ngx_change_binary 为 0] 


‘> 


[ngx_noaccept 标志 位 为 1] 














18) 向 有 所 有 子 进程 发 送 
QUIT 信 号 要 求 关 闭 服务 


图 8-8 ” ”master 进程 的 工作 循环 
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下 面 简要 介绍 一 下 图 8-8 中 列 出 的 流程 。 实 际 上 ， 根 据 以 下 8 个 标志 位 : ngx_reap、 
ngx terminate、 ngx quit、 ngx reconfieure、ngx restart、ngx reopen、ngx change binary、 
ngx_noaccept， 决 定 执行 不 同 的 分 文 流 程 ， 并 循环 执行 “注意 ， 每 次 一 个 循环 执行 完毕 后 进 
程 会 被 挂 起 ， 直 到 有 新 的 信号 才 会 激活 继续 执行 ) 。 


1) 如 果 ngx_reap 标 志 位 为 0， 则 继续 向 下 执行 第 2 步 ， 如 果 ngx_reap 标 志 位 为 1， 则 表示 
需要 监控 所 有 的 子 进程 ， 同 时 调用 表 8-2 中 的 ngx_reap_children 方 法 来 管理 子 进程 。 这 时 ， 
ngx_reap_children 方 法 将 会 遍历 ngx_processes 数 组 ， 检 查 每 个 子 进程 的 状态 ， 对 于 非 正 常 退出 
的 子 进程 会 重新 拉 起 。 最 后 ，ngx_processes 方 法 会 返回 一 个 live 标 志 位 ， 如 果 所 有 的 子 进程 
都 已 经 正常 退出 ， 那 么 live 将 为 0， 除 此 之 外 ，1live 会 为 1。 











2) 当 live 标 志 位 为 0〈 所 有 子 进程 已 经 退出 ) 、ngx terminate 标 志 位 为 1 或 者 ngx quit 标志 
位 为 1 时 ， 都 将 调用 ngx master process_exit 方 法 开始 退出 master 进 程 ， 人 否则 继续 辐 下 执行 第 6 
步 。 在 ngx_master process_exit 方 法 中 ， 首 先 会 删除 存储 进程 号 的 pid 文 件 。 


3) 继续 之 前 的 ngx master process_exit 方 法 ， 调 用 所 有 模块 的 exit master 方 法 。 
4) 调用 ngx close listening sockets 方 法 关闭 进程 中 打开 的 监听 端口 。 
5) 销毁 内 存 池 ， 退 出 master 进 程 。 


6) 如 果 ngx terminate 标 志 位 为 1， 则 癌 所 有 子 进 程 发 送信 号 TERM， 通 知 子 进程 强制 退 
出 进程 ， 接 下 来 直接 跳 到 第 1 步 并 挂 起 进程 ， 等 竺 信号 激活 进程 。 如 果 ngx terminate 标 志 位 为 


0， 则 继续 执行 第 7 步 。 








7) 如 末 ngx_quit 标 志 位 为 0， 跳 到 第 9 步 ， 否 则 表示 需要 优雅 地 退出 服务 ， 这 时 会 同 所 有 
子 进程 发 送 QUIT 信 和 号， 通知 它们 退出 进程 。 








8) 继续 ngx_guit 为 1 的 分 支流 程 。 关 闭 所 有 的 监听 端口 ， 接 下 来 直接 跳 到 第 1 步 并 挂 起 
ter 进 程 。 等 徒 信号 激活 进程 8 
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9) 如 果 ngx_reconfigure 标 志 位 为 0%， 则 跳 到 第 13 步 检查 ngx_restart 标 志 位 。 如 果 
ngx_reconfigure 为 1， 则 表示 需要 重新 读 取 配 置 文件 。Nginx 不 会 再 让 原先 的 worker 等 子 进程 再 
重新 读 取 配置 文件 ， 它 的 策略 是 重新 初始 化 ngx_cycle t 结 构 体 ， 用 它 来 读 取 新 的 配置 文件 ， 
再 拉 起 新 的 worker 进 程 ， 销 毁 旧 的 worker 进 程 。 本 步 中 将 会 调用 ngx_init_ cycle 方法 重新 初始 
化 ngx_cycle tt 结构 体 。 


10) 接 第 9 步 ， 调 用 ngx start worker processes 方 法 再 拉 起 一 批 worker 进 程 ， 这 些 worker 
进程 将 使 用 新 ngx_cycle t 结 构 体 。 


11) 接 第 10 步 ， 调 用 ngx start cache manager processes 方 法 ， 按 照 缓存 模块 的 加 载 情况 
决定 是 否 拉 起 cache manage 或 者 cache loader 进 程 。 在 这 两 个 方法 调用 后 ， 肯 定 是 存在 子 进程 
了 ， 这 时 会 把 live 标 志 位 置 为 ! (第 2 步 中 曾 用 到 此 标志 〉。 





12) 接 第 11 步 ， 回 原先 的 “并 非 刚刚 拉 起 的 ) 所 有 子 进程 友 送 QUIT 信 和 号， 要 求 它们 优 
雅 地 退出 自己 的 进程 。 





13) 检查 ngx restart 标 志 位 ， 如 果 为 0， 则 继续 第 1$ 步 ， 检 查 ngx reopen 标 志 位 。 如 果 
ngx restart 为 1， 则 调用 ngx start worker processes 方 法 拉 起 worker 进 程 ， 同 时 将 ngx restart 置 
为 0。 





14) 接 13 步 ， 调 用 ngx start cache manager processes 方 法 根据 缓存 模块 的 情况 选择 是 否 
启动 cache manage 进 程 或 者 cache loader 进 程 ， 同 时 将 live 标 志 位 置 为 1。 





15) 检查 ngx reopen 标 志 位 ， 如 果 为 0， 则 继续 第 17 步 ， 检 查 ngx change_ binary 标志 位 。 
如 果 ngx reopen 为 1， 则 调用 ngx reopen files 方 法 重新 打开 所 有 文件 ， 同 时 将 ngx reopen 标 志 
位 置 为 0。 





16) 问 所 有 子 进程 发 送 USR1 信 和 号， 要求 子 进 程 都 得 重新 打开 所 有 文件 。 


a 














Nginx， 这 时 将 调用 ngx_exec_new_binary 方 法 用 新 的 子 进程 启动 新 版 本 的 Nginx 程 序 ， 同 时 将 
ngx change_binary 标 志 位 置 为 0。 


18) 检查 ngx_noaccept 标 志 位 ， 如 果 ngx_noaccept 为 0， 则 继续 第 1 步 进 行 下 一 个 循环 ; 如 
朵 ngx_noaccept 为 1， 则 向 所 有 的 子 进 程 友 送 QUIT 信 与 ， 要 求 它 们 优雅 地 关闭 服务 ， 同 时 将 
ngxX noaccept 置 为 0， 并 将 negx noaccepting 置 为 1， 表 示 正 在 停止 接受 新 的 连接 。 





注意 ， 在 以 上 18 个 步骤 组 成 的 循环 中 ， 并 不 是 不 停 地 在 循环 执行 以 上 步骤 ， 而 是 会 通过 
sigsuspend 调 用 使 master 进 程 休眠 ， 等 待 master 进 程 收 到 信号 后 激活 master 进 程 继续 由 上 面 的 第 
1 步 执行 循环 。 
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8.7 negx pool t 内 存 池 


在 说 明 其 设计 前 先 来 看 看 与 ngx_pool t 内 存 池 相关 的 15 个 方法 ， 如 表 8-5 所 示 。 


表 8-5 内存 池 操 作 方 法 
方法 类 总 


创建 内 存 池 ， 注 意 它 的 size 参数 并 不 等 同 于 可 分 配 空间 ， 
它 同 时 包含 了 管理 结构 的 大 小 ， 这 意味 着 : size 绝 不 能 小 于 
sizeof ( ngx_pool t)， 和 否则 就 会 有 内 存 越界 错误 。 通 常 ， 可 以 
设 Size 为 NGX _ DEFAULT POOL _ SIZE， 该 安 目前 为 16KB， 
不 用 担心 16KB 会 不 够 用 ， 当 这 第 一 个 16KB 用 完 时 ， 会 自动 
再 分 配 16KB 内 存 的 


ngx create pool 


内 存 池 操 作 


销毁 内 存 池 ， 它 同时 会 把 通过 该 pool 分 配 出 的 内 存 释 放 ， 
ngx_destroy_pool 而 且 ， 还 会 执行 通过 ngx_pool_cleanup_add 方 法 添加 的 各 类 


资源 清理 方法 

重 置 内 存 池 ， 即 将 内 存 池 中 的 原 有 内 存 释 放 后 继续 使 用 
ngx_ reset_pool 这 个 方法 的 实现 是 ， 会 把 大 块 内 存 释放 给 操作 系统 ， 而 小 块 
内 存 则 在 不 释放 的 情况 下 复 用 
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( 续 ) 


方法 类 型 意义 
分 配 地 址 对 齐 的 内 存 。 按 总 线 长 度 (例如 sizeof ( unsigned 
ngx_palloc long)) 对 齐 地 址 后 ， 可 以 减少 CPU 读 取 内 存 的 次 数 ， 当 然 代 


价 是 有 一 些 内 存 浪 费 


人 本 同时 不 进行 让 


[am | 分 配 出 地 址 对 齐 的 内 存 后 ， 再 调用 memset 将 这 些 内 存 全 部 
ngx_pcalloc 
基于 内 存 池 的 


分 配 。 释 放 内 存 按 人 参数 alignment 进行 地 址 对 齐 来 RE 注意 ， 这 样 分 
操作 i 配 出 的 内 存 不 管 申 请 的 size 有 多 小 ， 都 是 不 会 使 用 小 块 内 存 

要 池 的 ， 它 会 从 进程 的 堆 中 分 配 内 存 ， 并 挂 在 大 块 内 存 组 成 的 
large 单 链表 中 


提前 释放 大 块 内 存 。 它 的 效率 不 高 ， 其 实现 是 遍历 large 链 
表 ， 寻 找 ngx_pool large t 的 alloc 成 员 等 于 待 释 放 地 址 ， 找 
nox Tree 
本 到 后 释放 内 存 给 操作 系统 ， 将 ngx_ pool large t 移 出 链表 并 
删除 


第 加 一 个 半 要 在 内 存 池 释放 时 同步 释放 的 资源 。 该 方法 会 
返回 一 个 ngx_pool cleanup 1 结构 体 ， 而 我 们 得 到 后 需要 设置 
eg 的 handler 成 员 为 释放 资源 时 执行 的 方法 。 
ngx_ pool cleanup add ngx_pool_cleanup add 有 一 个 参数 size， 当 它 不 为 0 时 ,会 分 
配 size 大 小 的 内 存 ， 并 将 _cleanup t 的 data 成 员 指 
向 该 内 存 ， 这 样 可 以 利用 这 段 内 存 传递 参数 ， 供 释放 资源 的 





随 着 内 存 池 释 ee 
放 同 步 释 放 资 源 在 内 存 池 释放 前 ， 如 果 需 要 提前 关闭 文件 (当然 是 调用 过 


的 操作 ngx_pool_ cleanup add 添加 的 文件 ， 同 时 ngx_pool cleanup_ 


t 的 handler 成 员 被 设 为 ngx pool cleanup file)， 则 调用 该 
方法 


以 关闭 文件 来 释放 资源 的 方法 ， 可 以 设置 到 ngx_pool_ 
ngx_ pool cleanup file 和 
cleanup t 的 handler 成 员 
以 删除 文件 来 释放 资源 的 方法 ， 可 以 设置 到 ngx pool_ 
ngx_pool delete file 
cleanup t 的 handler 成 员 


em 从 操作 系统 中 分 配 内 存 
| nex ealoe | 从 操作 系统 中 分 配 出 内 存 ， 再 调用 memset 把 内 存 清 
的 分 配 、 释 放 操作 ngx_calloc 从 操作 系统 中 分 配 和 再 调用 memset 把 内 存 清 0 
人 
Nginx 己 经 提供 封装 了 malloc、free 的 ngx alloc、ngx free 方 法 ， 为 什么 还 需要 一 个 挺 复 杂 
的 内 存 池 呢 ?对 于 没有 垃圾 回收 机 制 的 C 语 言 编 写 的 应 用 来 襄 ， 最 容易 犯 的 错 就 是 内 存 泄 
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ngx_ pool run cleanup file 








露 。 当 分 配 内 存 与 释放 内 存 的 逻辑 相距 遥远 时 ， 还 很 容易 发 生 同 一 块 内 存 被 释放 两 次 。 内 存 
池 就 是 为 了 降低 程序 员 犯 错 几 率 的: 模块 开发 者 只 需要 关心 内 存 的 分 配 ， 而 释放 则 交 由 内 存 
池 来 负责 。 








那么 ，ngx_pool {t 内 存 池 什么 时 候 会 释放 内 存 呢 ? 一 般 地 ， 内 存 池 销毁 时 才 会 将 内 存 释 
放 回 操作 系统 (例外 就 是 表 8-5 中 的 ngx_pfree 方 法 ) 。 在 一 个 内 存 池上 ， 可 以 任意 次 的 申请 
内 存 ， 不 用 释放 它们 ， 唯 一 要 做 的 就 是 记得 销毁 内 存 池 。 这 一 策略 在 降低 程序 员 们 出 错 概率 
的 同时 ， 引 入 了 男 一 问题 ， 如 果 这 个 内 存 池 的 生命 周期 很 长 ， 而 每 一 块 内 存 的 生命 周期 很 
短 ， 早 期 申请 的 内 存 会 一 直 无 谓 地 占用 着 珍贵 的 内 存 资源 ， 这 不 是 造成 严重 的 内 存 浪 费 吗 ? 
比如 生成 内 存 池 后 1 天 后 销毁 它 ， 这 1 天 中 每 秒 申 请 IK 的 内 存 ， 而 申请 到 的 每 块 内 存在 这 一 
秒 中 就 已 经 使 用 完毕 ， 这 样 1 天 结束 时 这 个 内 存 池 已 经 占用 了 86MB 的 内 存 ! 没 错 ， 如 果 内 存 
与 内 存 池 的 生命 周期 是 如 此 差异 ， 那 么 这 个 问题 是 存在 的 。 所 以 ， 一 般 性 的 应 用 中 没有 见 过 
这 样 的 内 存 池 设计 。 但 是 ngx_pool t 内 存 池 却 可 以 应 用 在 Nginx 上 ， 这 是 因为 Nginx 是 一 个 很 纯 
粹 的 web 服 务 器 ， 与 客户 站 的 每 一 个 TCP 连 接 有 明确 的 生命 周期 ，TCP 连 接 上 的 每 一 个 HTTP 
请 求 有 非常 短暂 的 生命 周期 ， 如 果 每 个 请 求 、 连 接 都 有 各 自 的 内 存 池 ， 而 模块 开发 者 们 评估 
待 申 请 内 存 的 使 用 周期 ， 如 果 素 属于 一 个 HTTP 请 求 ， 则 在 请 求 的 内 存 池 上 分 配 内 存 ， 如 果 
隶属 于 一 个 连接 ， 则 在 连接 的 内 存 池 上 分 配 内 存 ， 如 果 一 直 伴随 着 模块 ， 则 可 以 在 
ngx_conf t 的 内 存 池上 分 配 内 存 。 似 乎 我 们 得 到 了 不 用 释放 内 存 的 好 处 ， 却 增加 了 关心 内 存 
生命 周期 的 额外 工作 ? 事实 不 是 这 样 的 ， 绝 大 多 数 模块 都 在 单纯 的 处 理 请 求 ， 只 需要 使 用 
ngx_http request t 中 的 内 存 池 即 可 。 























ngx_pool {内 存 池 的 设计 上 还 考虑 到 了 小 块 内 存 的 频繁 分 配 在 效率 上 有 提升 空间 ， 以 及 
内 存 碎 片 还 可 以 再 减少 些 。 在 讨论 其 实现 前 ， 先 定义 什么 叫 小 块 内 存 ， 
NGX MAX ALLOC FROM POOL 宏 是 一 个 很 重要 的 标准 : 





#define NGX MAX ALLOC FROM POOL (ngx pagesize - 1) 
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可 见 ， 在 X86 架 构 上 就 是 4095 字 节 。 通 香 ， 小 于 等 于 NGX_MAX ALLOC FROM POOL 
就 意味 着 小 块 内 存 。 这 并 不 是 绝对 的 ， 当 调用 ngx_create pool 创建 内 存 池 时 ， 如 果 传 递 的 size 
参数 小 于 NGX MAX ALLOC FROM POOL+sizeoftngx pool D， 则 对 于 这 个 内 存 池 来 说 ， 
size-sizeofngx_ pool 0D 字 节 就 是 小 块 内 存 的 标准 。 大 块 内 存 与 小 块 内 存 的 处 理 很 不 一 样 ， 看 
看 ngx_pool t 的 定义 就 知道 了 : 





typedef struct ngx Pool s ngx Pool t; 
struct ngx pool s { 


// 描述 小 块 内 存 池 。 当 分 配 小 块 内 存 时 ， 剩 余 的 预 分 配 空间 不 足 时 ， 会 再 分 
1 个 


ngx pool 七 ， 


// 它们 会 通过 
d 中 的 


next 成 员 构 成 单 链表 


ngx pool data t 
1 人 让 宙 内 二 汪 收 物 巡 世 央 挫 科 各 兴 


size 七 


// 多 个 小 次 肖 痊 池 蜀 城 畦 天 半 。 
current 指 向 分 配 内 存 时 遍历 的 第 


1 个 小 块 内 存 池 


ngx pool 七 *ourrent; 


// 用 于 


ngx_output_chain， 与 内 存 池 关系 不 大 ， 略 过 


ngx chain 七 *chain; 


// 大 块 内 存 都 直接 从 进程 的 堆 中 分 配 ， 为 了 能 够 在 销毁 内 存 池 时 同时 释放 大 块 内 存 ， 


// 就 把 每 一 次 分 配 的 大 块 内 存 通过 


ngx pool large 组 成 单 链表 挂 在 
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large 成 员 上 


ngx pool large t *large; 


// 所 有 待 清理 资源 (例如 需要 关闭 或 者 删除 的 文件 ) 以 


ngx pool cleanup 七 对 象 构 成 单 链表 ， 


// 挂 在 


cleanup 成 员 上 


ngx pool cleanup t *cleanup; 


// 内 存 池 执行 中 输出 日 志 的 对 象 


ngx log t GOg7 
}; 





从 上 面 代 码 的 注释 中 可 知 ， 当 申请 的 内 存 算 是 大 块 内 存 时 (大 于 ngx pool t 的 max 成 
员 ) ， 是 直接 调用 ngx alloc 从 进程 的 堆 中 分 配 的 ， 同 时 会 再 分 配 一 个 ngx pool large t 结 构 体 
挂 在 large 链 表 中 ， 其 定义 如 下 : 





typedef struct ngx pool large s ngx pool large tt; 
struct ngx pool large s { 


// 所 有 大 块 内 存 通过 





next 指 针 联 在 一 起 


ngx pool large t *next; 


// alloc 指 向 


ngx alloc 分 配 出 的 大 块 内 存 。 


ngx_pfree 后 


alloc 可 能 是 


void *allLOG; 








对 于 非常 大 的 内 存 ， 如 果 它 的 生命 周期 远 远 的 短 于 所 属 的 内 存 池 ， 那 么 在 内 存 池 销毁 前 
提前 的 释放 它 就 变 得 有 意义 了 。 而 ngx_pfree 方 法 就 是 提前 释放 大 块 内 存 的 ， 需 要 注意 ， 它 的 
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实现 是 遍历 large 链 表 ， 找 到 alloc 等 于 待 释放 地 址 的 ngx pool large t 后 ， 调 用 ngx free 释 放大 
块 内 存 ， 但 不 释放 ngx_pool_large t 结 构 体 ， 而 是 把 alloc 置 为 NULL。 如 此 实现 的 意义 在 于 : 
下 次 分 配 大 块 内 存 时 ， 会 期 望 复 用 这 个 ngx pool large tt 结构 体 。 从 这 里 可 以 想见 ， 如 果 large 
链表 中 的 元 素 很 多 ， 那 么 ngx_free 的 遍历 损耗 的 性 能 是 不 小 的 ， 如 果 不 能 确定 内 存 确实 非常 
大 ， 最 好 不 要 调用 ngx pfree。 





再 来 看 看 小 块 内 存 ， 通 过 从 进程 的 堆 中 预 分 配 更 多 的 内 存 (ngx_create_pool 的 size 参 数 决 
定 预 分 配 大 小 ) ， 而 后 直接 使 用 这 块 内 存 的 一 部 分 作为 小 块 内 存 返 回 给 申请 者 ， 以 此 实现 减 
少 碎片 和 调用 malloc 的 次 数 。 它 们 是 放 在 成 员 d 中 维护 管理 的 ， 看 看 ngx pool data t 是 如 何 定 
义 的 : 








typedef struct { 
// 指向 未 分 配 的 空闲 内 存 的 首 地 址 


t Char 人 Gy 


吕 last; 
// 指向 当前 小 块 内 存 池 的 尾部 


u char *end; 


// 同属 于 一 个 
pool 的 多 个 小 块 内 存 池 间 ， 通 过 


next 相 连 


ngx pool t *next; 
// 每 当 剩余 空间 不 足以 分 配 出 小 块 内 存 时 ， 


failed 成 员 就 会 加 
i 
failed 成 员 大 于 


4 后 


// ( 


Nginx1.4.4 版 本 ) 


口 由 掉 岂 有 由 和 和 有 由 http' /wNv inuxorobe. con 





ngx Pool 七 的 


current 将 移 向 下 一 个 小 块 内 存 池 


ngx uint t failed; 
} ngx pool data t; 





当 内 存 池 预 分 配 的 size 不 足 使 用 时 ， 殊 会 再 接 者 分 配 一 个 小 块 内 存 池 ， 预 分 配 大 小 与 原 
内 存 池 相等 ， 且 仍然 使 用 ngx_pool {于 示 这 个 纯粹 的 小 块 内 存 池 ， 用 ngx_pool_data_t 的 next 成 
员 相 连 。 这 样 ， 这 个 新 增 的 ngx_pool tt 结构 体 中 与 小 块 内 存 无 关 的 其 他 成 员 此 时 是 无 意义 
的 ， 例 如 max 不 会 赋值 、large 链 表 为 空 等 。 








ngx_pool t 不 只 希望 程序 员 不 用 释放 内 存 ， 而 且 还 能 不 需要 释放 如 文件 等 资源 。 例 如 第 
12 章 介绍 的 upstream 实 现 的 反 向 代理 ， 其 存放 http 协 议 包 体 的 文件 就 希望 它 可 以 随 着 
ngx_pool t 内 存 池 的 销毁 被 自动 关闭 并 删除 挤 。 怎 么 实现 呢 ?” 表 8-5 中 的 ngx_pool cleanup add 
方法 就 用 来 提供 这 一 功能 ， 它 会 返回 ngx pool cleanup tt 结构 体 ， 其 定义 如 下 所 示 : 





// 实现 这 个 回调 方法 时 ， 
data 参 数 将 是 
ngx Pool cleanup pt 的 


data 成 员 


typedef void (*ngx pool cleanup pt) (void *data); 
typedef struct ngx pool cleanup s ngx pool cleanup t; 
struct ngx pool cleanup s { 

// handler 初 始 为 


NULL， 需 要 设置 为 清理 方法 


ngx pool cleanup pt handler; 
// ngx pool cleanup add 方 法 的 


size>0 时 
data 不 为 


NULL， 此 时 可 改写 
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data 指 向 的 内 存 ， 


// 用 于 为 


handler 指 向 的 方法 传递 必要 的 参数 


void *data; 


// 由 


ngx pool cleanup adg 方 法 设置 


next 成 员 ， 用 于 将 当前 


ngx pool cleanup t 


// 添加 到 


ngx Pool 七 的 


cleanup 链 表 中 


ngx pool _ cleanup t *next; 


}; 





3.8.2 市 就 是 一 个 很 好 的 资源 释放 例子 ， 当 我 们 将 handler 设 为 表 8-5 中 的 
ngx pool_delete_file 方 法 时 可 以 删除 文件 。 


图 8-9 完 整地 展示 了 ngx_pool t 内 存 池 中 小 块 内 存 、 大 块 内 存 、 资 源 清理 链表 间 的 关系 。 
图 中 ， 内 存 池 预 分 配 的 小 块 内 存 区 域 剩 余 空闲 空间 不 足以 分 配 某 些 内 存 ， 导 致 又 分 配 出 2 个 
小 块 内 存 池 。 其 中 原 内 存 池 的 failed 成 员 已 经 大 于 4， 所 以 current 指 向 了 第 2 个 小 块 内 存 池 ， 这 
样 再 次 分 配 小 块 内 存 时 将 会 忽略 第 1 个 小 块 内 存 池 。【〔 从 这 里 可 以 看 到 ， 分 配 内 存 的 行为 可 
能 导致 每 个 内 存 池 最 大 NGX MAX ALLOC FROM POOL-1 字 节 的 内 存 浪费 。) 图 中 共 分 配 3 
个 大 块 内 存 ， 其 中 第 2 个 大 块 内 存 调 用 过 ngx_pfree 方 法 释放 了 。 图 中 还 挂 载 了 两 个 资源 清理 
方 汪 ， 








图 8-10 以 分 配 地 址 对 齐 的 内 存 为 例 ， 列 出 了 主要 步 又 的 流程 图 ， 可 以 给 读者 朋友 们 更 直 
观 的 印象 ， 下 面 详细 解释 各 步 又: 


TiNNNNNinNnnn http://wWwWw linuxorobe.con 





1) 将 申请 的 内 存 大 小 size 与 ngx pool t 的 max 成 员 比 较 ， 以 决定 申请 的 是 小 块 内 存 还 是 大 


块 内 存 。 如 末 size<=max， 则 继续 执行 第 2 步 开 始 分 配 小 块 内 存 ， 否 则 ， 跳 到 第 10 步 分 配 大 块 


内 存 。 
2) 取 到 ngx_pool t 的 current 指 针 ， 它 表示 应 当 首 先 和 尝试 从 这 个 小 块 内 存 池 里 分 配 ， 因 为 





current 之 前 的 pool 已 经 屡次 分 配 失败 〈 大 于 4 次 ) ， 其 剩余 的 空间 多 半 无 法 满足 size。 这 当然 


古 一 种 存在 浪费 的 预 估 ， 但 性 能 不 坏 。 
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图 8-9 ngx_pool t 资 源 池 示意 图 


3) 从 当前 小 块 内 存 池 的 ngx pool data t 的 last 指 针 入 手 ， 先 调用 ngx align ptr 找到 last 后 
最 近 的 对 齐 地 址 。〈 可 参考 第 16 章 的 slab 共 享 内 存 ， 那 里 处 处 需要 地 址 对 齐 。) 





#define ngx align ptr(p, a) \ 

(u char *) (((uintptr t) (p) + ((uintptr t) a ~- 1)) & ~((uintptr t) a - 1)) 
#define NGX ALIGNMENT sizeof (unsigned long) 
ngx pool t  *p = 





// 取得 
last 的 


NGX_ALIGNMENT 字 节 对 齐 地 址 





uU char* m = ngx align ptr(p->d.last, NGX ALIGNMENT); 











4) 比较 对 齐 地 址 与 ngx pool data t 的 end 指 针 间 是 否 可 以 容纳 size 字 节 。 如 果 end- 
m>=size， 那 么 继续 执行 第 5 步 准备 返回 地 址 m;， 否则， 再 检查 ngx_pool_data_{t 的 next 指 针 是 否 
为 NULL， 如 果 是 空 指针 ， 那 么 跳 到 第 6 步 准 备 再 申请 新 的 小 块 内 存 池 ， 不 为 空 则 跳 到 第 3 步 
继续 遍历 小 块 内 存 池 构成 的 链表 。 





5) 先 将 ngx pool data t 的 last 指 针 置 为 下 次 空 亲 内 存 的 首 地 址 ， 例 如 : 





p->d.last = m + size; 





再 返回 地 址 m， 分 配 内 存 流程 结 


6) 分 配 一 个 大 小 与 上 一 个 ngx_pool {一致 的 内 存 池 专 用 于 小 块 内 存 的 分 配 。 内 存 池 大 小 
获取 很 简单 ， 如 下 : 





(size t) ( pool->d.end - (u char *) pool) 





jp 对 En ls ae， 内 内 存 
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的 首 地 址 。 


8) 从 current 指 同 的 小 块 内 存 池 开始 遇 历 到 当前 的 新 内 存 池 ， 依 次 将 各 failed 成 员 加 1， 并 
把 current 指 回首 个 failed<=4 的 小 块 内 存 池 ， 用 于 下 一 次 的 小 块 内 存 分 配 。 


9) 返回 第 7 步 对 齐 的 地 址 ， 分 配 流程 结 
10) 调用 ngx_alloc 方 法 从 进程 的 堆 内 存 中 分 配 size 大 小 的 内 存 。 


11) 遍历 ngx pool t 的 large 链 表 ， 看 看 有 没有 ngx_pool_large t 的 alloc 成 员 值 为 NULL (这 
个 alloc 指 向 的 大 块 内 存 执 行 过 ngx pfree 方 法 ) 。 如 果 找 到 了 这 个 ngx pool large t， 继 续 执 行 
第 12 步 ， 否则 ， 跳 到 第 13 步 执行 。 需 要 注意 的 是 ， 为 了 防止 large 链 表 过 大 ， 遍 历次 数 是 有 限 
制 的 ， 例 如 最 多 4 次 还 未 找到 alloc==NULL 的 元 素 ， 也 会 跳出 这 个 遍历 循环 执行 第 13 步 。 





12) 把 ngx pool large t 的 alloc 成 员 置 为 第 10 步 分 配 的 内 存 地 址 ， 返 回 地 址 ， 分 配 流程 结 
束 。 


13) 从 内 存 池 中 分 配 出 ngx pool large t 结 构 体 ，alloc 成 员 置 为 第 10 步 分 配 的 内 存 地 址 ， 
将 ngx pool large_t 添 加 到 ngx pool t 的 large 链 表 首 部 ， 返 回 地 址 ， 分 配 流程 结束 。 
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1 ) 将 分 配 大 小 size 与 ngx_pool_t 的 max 成 员 比 较 


[size<=max] 





< 








上 


Da 


2 ) 从 current 成 











指 问 的 ngx_poolLt 开 始 遍 历 pool 链 表 





3 ) 从 当前 ngx_pool_data_t 的 last 指 针 找 到 对 齐 地 址 


[size>max] 
4 ) 比较 新 地 址 与 end 之 前 的 空间 大 小 是 否 可 容纳 size 
[遍历 ] 





SS 








[找到 一 个 pool 可 以 分 出 size 地 址 ] 


[链表 中 的 所 有 pool 都 无 法 分 出 size 内 存 ] 





5 ) 设 last 为 对 齐 地 址 加 上 size， 返 回 对 齐 地 址 


6 ) 分 配 新 的 ngx_pool 1 ， 大 小 与 第 1 个 pool 一 致 





7 ) 对 齐 空闲 内 存 首 地 址 ， 重 置 last 指 针 





10 ) 分 配 一 块 size 大 小 的 内 存 
8 ) 检查 各 pool 的 failed 次 数 ， 重 置 current 指 针 








9 ) 返回 新 pool 分 配 出 的 对 齐 内 存 地 址 


11 ) 遍历 pool 的 large 链 表 ， 找 出 alloc=NULL 的 指针 


[未 找到 或 遍历 
[找到 alloc 值 为 NULL 的 成 员 ] 个 数 达到 上 限 ] 
铺 


12 ) 将 刚 分 配 内 存 赋 给 alloc， 并 返回 地 址 





13 ) 新 分 配 ngx_pool_large_t 结 构 赋 值 后 挂 在 large 链 表 上 ， 返 回 地 址 
图 8-10 


分 配 地 址 对 齐 内 存 的 流程 图 
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8.8 ”小 结 


本 章 主要 理 清 了 Nginx 的 设计 思路 ， 知 道 它 是 如 何 达 到 高 性 能 、 高 可 靠 性 、 高 可 伸缩 
性 、 蜗 可 修改 性 等 要 求 的 。 在 此 基础 上 ， 我 们 以 ngx_cycle 坝 据 结构 为 核心 ， 介 绍 了 Nginx 杠 
染 如 何 局 动 、 初 始 化 、 加 载 各 Nginx 模 块 的 代码 ， 以 及 master 进 程 、worker 进 程 如 何在 工作 循 
环 中 运行 。 对 于 worker 进 程 来 说 ， 它 的 工作 流程 更 多 地 体现 在 具体 的 模块 上 。 例 如 ， 对 于 
HTTP 请 求 来 说 ，worker 进 程 大 都 是 由 HTTP 模 块 所 占用 的 ， 特 别 是 8.5 节 中 提 到 的 
ngx_process_events_and_timers 方 法 ， 这 是 第 9 章 中 事件 模块 将 要 讲述 的 内 容 ， 因 此 ， 对 于 
worker 进 程 的 工作 循环 ， 本 章 并 没有 做 详细 的 说 明 。 对 于 master 进 程 ，8.6 市 内 容 基 本 上 涉及 
了 它 在 工作 循环 中 执行 的 所 有 流程 。 而 对 于 cache manage 和 cache loader 进 程 ， 它 们 是 与 文件 
缓存 模块 密切 相关 的 ， 在 不 使 用 文件 缓存 时 ， 这 两 个 进程 也 不 会 启动 ， 它 们 与 框 染 代 码 没 有 
多 少 关 联 ， 本 章 只 是 进行 了 简单 说 明 。 

















ngx_pool t 内 存 池 是 一 个 很 基础 的 设计 ， 本 章 通 过 分 析 其 实现 可 以 帮助 读者 朋友 们 正确 
地 使 用 ngx_pool {t 内 存 池 ， 方 便 阅 读 后 续 章节 。 


通过 阅读 本 章 的 内 容 ， 该 者 应 该 对 Nginx 的 设计 结构 有 了 大 致 的 了 解 ， 这 样 在 修改 Nginx 
的 源码 或 者 开发 一 些 异 常 强大 且 深 入 的 Nginx 模 块 时 就 可 以 得 心 应 手 了 ， 因 为 只 有 在 不 违反 
Nginx 本 身 设 计 原 则 的 前 提 下 才 会 保留 8.2 节 中 所 述 的 优点 。 同 时 ， 本 章 内 容 是 后 续 草 市 的 基 
础 ， 在 了 解 事件 模块 、HTTP 模 块 、mail 模 块 前 ， 必 须 对 Nginx 整 个 的 模块 分 布 、 事 件 驱 动 、 
请 求 的 多 阶段 划分 等 特点 有 清晰 的 认识 ， 这 样 在 阅读 后 续 章 节 时 可 以 做 到 事半功倍 。 
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第 9 草 ”事件 模块 





在 上 文中 提 到 ，Nginx 是 一 个 事件 驱动 架构 的 Web 服 务 器 ， 本 章 将 全 面 探 讨 Nginx 的 事件 
驱动 机 制 是 如 何 工作 的 。ngx_event t 事 件 和 ngx_connection t 连 接 是 处 理 TCP 连 接 的 基础 数据 
结构 ， 在 对 它们 有 了 基本 了 解 后 ， 在 9.4 贡 将 首先 探讨 核心 模块 ngx_events module， 它 定义 了 
一 种 新 的 模块 类 型 一 事件 模块 ， 而 在 9.5 节 将 开始 说 明 第 1 个 事件 模块 
ngx_event core module， 它 的 职责 更 多 地 体现 在 如 何 管理 当前 正在 使 用 的 事件 驱动 模式 。 例 
如 ， 在 Nginx 启 动 时 决定 到 底 是 基于 select 还 是 epoll 来 监控 网 络 事件 。 











epoll 是 目前 Linux 操 作 系 统 上 最 强大 的 事件 管理 机 制 ， 本 书 描述 的 场景 都 是 使 用 epoll 来 
驱动 事件 的 处 理 ， 在 9.6 节 中 ， 首 先 会 深入 到 Linux 内 核 ， 研 究 epoll 的 实现 原理 和 使 用 方法 ， 
以 此 明确 epoll 的 高 并 发 是 怎么 来 的 ， 以 及 怎样 使 用 epol 才 能 发 挥 它 的 最 大 性 能 。 接 着 ， 就 到 
了 ngx_epoll_ module 模 块 “亮相 ”的 时 候 了 ， 这 里 可 以 看 到 一 个 实际 的 事件 驱动 模块 是 如 何 实 
现 声 明 过 的 事件 抽象 接口 的 〈 见 9.1 节 ) ， 同 时 这 个 模块 也 是 高 效 使 用 epoll 的 较 好 的 例子 。 
例如 ， 在 使 用 epoll 时 ， 非 常 容易 遇 到 过 期 事件 的 处 理 问 题 ，Nsginx 就 使 用 了 一 个 巧妙 的 、 成 
本 低廉 的 方法 完美 地 解决 了 这 个 问题 ， 稍 后 读者 将 会 看 到 这 个 小 技巧 。 




















Nginx 的 定时 器 事件 是 由 第 7 章 中 谈 到 的 红 黑 树 实现 的 ， 它 也 由 epoll 等 事件 模块 触发 ， 在 
9.7 节 中 ， 读 者 将 看 到 Nginx 如 何 实 现 独 立 的 定时 器 功能 。 


在 9.8 节 中 ， 我 们 开始 综合 性 地 介绍 事件 处 理 框架 ， 这 里 将 会 使 用 到 9.1 节 ~9.7 节 中 的 所 
有 知识 。 这 一 节 将 说 明 核 心 的 ngx_process_events_and_timers 方 法 处 理 网 络 事 件 、 定 时 器 事 
件 、post 事 件 的 完整 流程 ， 同 时 读者 会 看 到 Nginx 是 如 何 解决 多 个 worker 子 进程 监听 同一 端口 
引起 的 “ 恢 群 ?现象 的 ， 以 及 如 何 均衡 多 个 worker 子 进程 上 处 理 的 连接 数 。 


毫 无 疑问 ，Linux 内 核 提供 的 文件 异步 JO 是 不 同 于 glibc 库 实现 的 多 线程 伪 异 步 JO 的 ， 它 
充分 利用 了 在 Linux 内 核 中 CPU 与 VO 设 备 独立 工作 的 特性 ， 使 得 进程 在 提交 文件 异步 JO 操 作 
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后 可 以 占用 CPU 做 其 他 工作 。 在 9.9 节 中 ， 将 会 讨论 这 种 高 效 读 取 磁 盘 的 机 制 ， 在 简单 说 明 它 
的 使 用 方式 后 ， 读 者 还 可 以 看 到 文件 异步 JO 是 如 何 集成 到 ngx_epoll_ module 模 块 中 与 epoll 一 
起 工作 的 。 


NNn httpo://ww linuxorobe. con 





9.1 事件 处 理 框架 概述 


事件 处 理 框 染 所 要 解决 的 问题 是 如 何 收集 、 管 理 、 分 及 事件 。 这 里 所 说 的 事件 ， 主 要 以 
网 络 事件 和 定时 器 事件 为 主 ， 而 网 络 事件 中 又 以 TCP 网 络 事件 为 主 〈Nginx 毕 竟 是 个 Web 服 务 
锻 ) ， 本 章 所 述 的 事件 处 理 框架 都 将 围 纸 这 两 种 事件 进行 。 











定时 器 事件 将 在 9.7 节 中 阐述 ， 因 为 它 的 实现 简单 而 且 独 立 ， 同 时 它 基 于 网 络 事件 的 触 
发 实现 ， 并 不 涉及 操作 系统 内 核 。 这 里 先 来 了 解 一 下 Nginx 是 如 何 收集 、 管 理 TCP 网 络 事件 
的 。 由 于 网 络 事件 与 网 卡 中 断 处 理 程序 、 内 核 提 供 的 系统 调用 密切 相关 ， 所 以 网 络 事件 的 驱 
动 既 取 诀 于 不 同 的 操作 系统 平台 ， 在 同一 个 操作 系统 中 也 受制 于 不 同 的 操作 系统 内 核 版 本 。 
这 样 的 话 ，Nginx 文 持 多 少 种 操作 系统 包括 支持 哪些 版 本 ) ， 就 必须 提供 多 少 个 事件 驱动 
机 制 ， 因 为 基本 上 每 个 操作 系统 提供 的 事件 驱动 机 制 (通常 事件 驱动 机 制 还 有 个 名 字 ， 叫 做 
IO 多 路 复 用 ) 都 是 不 同 的 。 例 如 ，Linux 内 核 2.6 之 前 的 版 本 或 者 大 部 分 类 UNIX 操 作 系 统 都 可 
以 使 用 poll (ngx_poll_module 模 块 实现 ) 或 者 select (ngx select_ module 模 块 实现 ) ， 而 Linux 
内 核 2.6 之 后 的 版 本 可 以 使 用 epoll (ngx epoll module 模 块 实现 ) ，FreeBSD 上 可 以 使 用 
kqueue (ngx_kqueue_module 模 块 实现 ) ，Solaris 10 上 可 以 使 用 


eventport (ngx eventport module 模 块 实现 ) 等 。 





如 此 一 来 ， 事 件 处 理 框 架 需 要 在 不 同 的 操作 系统 内 核 中 选择 一 种 事件 驱动 机 制 支持 网 络 
事件 的 处 理 (Nginx 的 高 可 移植 性 亦 来 源 于 此 〉 。Nginx 是 如 何 做 到 这 一 点 的 呢 ? 


首先 ， 它 定义 了 一 个 核心 模块 ngx events module， 这 样 在 Nginx 启 动 时 会 调用 
ngx init _ cycle 方法 解析 配置 项 ， 一 旦 在 nginx.conf 配 置 文件 中 找到 ngx_events _ module 感 兴趣 
的 “events{} ”配置 项 ，ngx_events_module 模 块 就 开始 工作 了 。 在 图 9-3 中 ，ngx_events_module 
模块 定义 了 事件 类 型 的 模块 ， 它 的 全 部 工作 就 是 为 所 有 的 事件 模块 解析 “events{}” 中 的 配置 
项 ， 同 时 管理 这 些 事件 模块 存储 配置 项 的 结构 体 。 
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其 次 ，Nginx 定 义 了 一 个 非常 重要 的 事件 模块 ngx_event_core_module， 这 个 模块 会 决定 使 
用 哪 种 事件 驱动 机 制 ， 以 及 如 何 管 理事 件 。 在 9.5 节 中 ， 将 会 详细 讨论 ngx_event core module 
模块 在 启动 过 程 中 的 工作 ， 而 在 9.8 节 中 ， 则 会 在 事件 框架 的 正常 运行 中 再 次 看 到 
ngx event core module 模 块 的 “身影 ”。 





最 后 ，Nginx 定 义 了 一 系列 (目前 为 9 个 ) 运行 在 不 同 操作 系统 、 不 同 内 核 版 本 上 的 事件 
驱动 模块 ， 包 括 : ngx epoll module、ngx kqueue module、ngx poll module、 
ngx Select module、 ngx devpoll module、 ngx eventport module、ngx alo module、 
ngx rtsig module 和 基于 Windows 的 ngx_ select module 模 块 。 在 ngx event core module 模 块 的 初 
始 化 过 程 中 ， 将 会 从 以 上 9 个 模块 中 选取 1 个 作为 Nginx 进 程 的 事件 驱动 模块 。 





下 面 开 始 介绍 事件 驱动 模块 接口 的 相关 知识 。 





事件 模块 是 一 种 新 的 模块 类 型 ，ngx_module_t 表 示 Nginx 模 块 的 基本 接口 ， 而 针对 于 每 一 
种 不 同类 型 的 模 世 ， 都 有 一 个 结构 体 来 描述 这 一 类 模块 的 通用 接口 ， 这 个 接口 保存 在 
ngx_module t 结 构 体 的 ctx 成 员 中 。 例 如 ， 核 心 模块 的 通用 接口 是 ngx_core_module t 结 构 体 ， 
而 事件 模块 的 通用 接口 则 是 ngx_event_module t 结 构 体 〈 参 见 图 8-1) ， 具 体 如 下 所 示 。 





typedef struct { 


// 事件 模块 的 名 称 


ngx str 七 *name; 


// create conf 和 


init conf 方 法 的 调用 可 参见 图 
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// 在 解析 配置 项 前 ， 这 个 回调 方法 用 于 创建 存储 配置 项 参数 的 结构 体 


void *(*create conf) (ngx cycle t *cycle); /* 在 解析 配置 项 完成 后 ， 


init_conf 方 法 会 被 调用 ， 用 以 综合 处 理 当前 事件 模块 感 兴趣 的 全 部 配置 项 


2 





char *(*init conf) (ngx cycle 七 cycle, voiqd conf); // 对 于 事件 驱动 机 制 ， 每 个 事件 模块 需要 实现 的 


10 个 抽象 方法 


ngx event actions t actions; 


} ngx event module t; 








ngx_event module t 中 的 actions 成 员 是 定义 事件 张 动 模块 的 核心 方法 ， 下 面 重 点 看 一 下 
actions 中 的 这 10 个 抽象 方法 ， 代 码 如 下 。 





typedef struct { 





/* 添 加 事件 方法 ， 它 将 负责 把 





1 个 感 兴趣 的 事件 添加 到 操作 系统 提供 的 事件 驱动 机 制 ( 如 
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epPol1、 


kqueue 等 ) 中 ， 这 样 ， 在 事件 发 生 后 ， 将 可 以 在 调用 下 面 的 


process_events 时 获取 这 个 事件 


4 


ngx int t (*add) (ngx event t *ev, ngx int t event, ngx uint t flags); /* 人 删除 事件 方法 ， 它 将 把 


1 个 已 经 存在 于 事件 驱动 机 制 中 的 事件 移 除 ， 这 样 以 后 即使 这 个 事件 发 生 ， 调 用 


process_events 方 法 时 也 无 法 再 获取 这 个 事件 


4 


ngx int t (*del) (ngx event t *ev, ngx int t event, ngx uint t flags); /* 启 用 








1 个 事件 ， 目 前 事件 框架 不 会 调用 这 个 方法 ， 大 部 分 事件 驱动 模块 对 于 该 方法 的 实现 都 是 与 上 面 的 


add 方 法 完全 一 致 的 


4 





ngx int t (*enable) (ngx event t *ev, ngx int t event, ngx uint t flags); /* 人 禁用 
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del 方 法 完全 一 致 的 


4 





ngx int 七 (*disapble) (ngx event t *ev, ngx int t event, ngx uint t flags); /* 向 事件 驱动 机 制 中 添加 一 个 新 的 连接 ， 设 


4 





ngx int 七 (*add conn) (ngx connection t *c); // 从 事件 驱动 机 制 中 移 除 一 个 连接 的 读 写 事件 


ngx int t (*del conn) (ngx connection t *c, ngx uint t flags); /* 仅 在 多 线程 环境 下 会 被 调用 。 目 前 ， 


Nginx 在 产品 环境 下 还 不 会 以 多 线程 方式 运行 ， 因 此 这 里 不 做 讨论 
*/ 


ngx int t (*process changes) (ngx cycle t *cycle, ngx uint 七 nowait); /* 在 正常 的 工作 循环 中 ， 将 通过 调用 


process_events 方 法 来 处 理事 件 。 这 个 方法 仅 在 第 


8 章 中 提 到 的 


ngx_process events and timers 方 法 中 调用 ， 它 是 处 理 、 分 发 事件 的 核心 
B24 


ngx int 七 (*process events) (ngx cycle t *cycle, ngx msec t timer, ngx uint t flags); // 初始 化 事件 驱动 模块 的 
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ngx int 七 (*init) (ngx cycle t *cycle, ngx msec t timer); // 退出 事件 驱动 模块 前 调用 的 方法 


void (*done) (ngx cycle 七 *cycle); 


} ngx event actions t; 
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9.2 ”Nginx 事 件 的 定义 


在 Nginx 中 ， 每 一 个 事件 都 由 ngx_event t 结 构 体 来 表示 。 本 市 说 明 ngx_event t 中 每 一 个 成 
员 的 含义 ， 如 下 所 示 。 





typedef struct ngx event s ngx event t; struct ngx event s { 





/* 事 件 相 关 的 对 象 。 通 常 


data 都 是 指向 


ngx_connection 七 连接 对 象 。 开 启 文件 异步 


ngx event aio 七 结构 体 





类 人 
void *data; 
/* 标 志 位 ， 为 
1 时 表示 事件 是 可 写 的 。 通 常情 况 下 ， 它 表示 对 应 的 
TCP 连 接 目前 状态 是 可 写 的 ， 也 就 是 连接 处 于 可 以 发 送 网 络 包 的 状态 
*/ 


unsigned write:1; 
/* 标 志 位 ， 为 
1 时 表示 为 此 事件 可 以 建立 新 的 连接 。 通 常情 况 下 ， 在 


ngx cycle 七 中 的 
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listening 动 态 数 组 中 ， 每 一 个 监听 对 象 


ngx listening 七 对 应 的 读 事件 中 的 


accept 标 志 位 才 会 是 


1 


unsigned accept:1; 





/* 这 个 标志 位 用 于 区 分 当前 事件 是 否 是 过 期 的 ， 它 仅仅 是 给 事件 驱动 模块 使 用 的 ， 而 事件 消费 模块 可 不 用 关心 。 为 什么 需要 这 个 标志 位 呢 ? 当 ] 


instance 标 志 位 来 避免 处 理 后 面 的 已 经 过 期 的 事件 。 在 


9.6 节 中 ， 将 详细 描述 


ngx_epol1 module 是 如 何 使 用 





instance 标 志 位 区 分 过 期 事件 的 ， 这 是 一 个 巧妙 的 设计 方法 


*/ 


unsigned instance:1; 


/* 标 志 位 ， 为 





1 时 表示 当前 事件 是 活跃 的 ， 为 











0 时 表示 事件 是 不 活跃 的 。 这 个 状态 对 应 着 事件 驱动 模块 处 理 方式 的 不 同 。 例 如 ， 在 添加 事件 、 删 除 事 件 和 处 理事 件 时 ， 





active 标 志 位 的 不 同 都 会 对 应 着 不 同 的 处 理 方 式 。 在 使 用 事件 时 ， 一 般 不 会 直接 改变 
active 标 志 位 
人 


unsigned active:1; 
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1 时 表示 禁用 事件 ， 仅 在 


kqueue 或 者 


rtsig 事 件 驱 动 模块 中 有 效 ， 而 对 于 





epoll 事 件 驱 动 模块 则 无 意义 ， 这 里 不 再 详 述 


4 


unsigned disabled:1; 


/* 标 志 位 ， 为 





1 时 表示 当前 事件 已 经 准备 就 绪 ， 也 就 是 说 ， 允 许 这 个 事件 的 消费 模块 处 理 这 个 事件 。 在 





HTTP 框 架 中 ， 经 常会 检查 事件 的 


ready 标 志 位 以 确定 是 否 可 以 接收 请 求 或 者 发 送 响应 





84 
unsigned ready:1; 
/* 该 标志 位 仅 对 
kqueue, 
eventport 等 模块 有 意义 ， 而 对 于 
Linux 上 的 
epol1 事 件 驱动 模块 则 是 无 意义 的 ， 限 于 篇 幅 ， 不 再 详细 说 明 
4 


unsigned oneshot:1; 
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AIO 事 件 的 处 理 ， 在 


9.9 节 中 会 详细 描述 


unsigned complete:1; 


// 标志 位 ， 为 


unsigned eof:1; 


// 标志 位 ， 为 





1 时 表示 事件 在 处 理 过 程 中 出 现 错误 


unsigned error:1; 





1 时 表示 这 个 事件 已 经 超时 ， 用 以 提示 事件 的 消费 模块 做 超时 处 理 ， 它 与 


timer set 都 用 于 


*/ 


unsigned timedout:1; 


// 标志 位 ， 为 





1 时 表示 这 个 事件 存在 于 定时 器 中 
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unsigned timer set:1; 


// 标志 位 ， 


delayed 为 


1 时 表示 需要 延迟 处 理 这 个 事件 ， 它 仅 用 于 限 速 功 能 





unsigned delayed:1; 


// 该 标志 位 目前 没有 使 用 


unsigned read discarded:1; 


// 标志 位 ， 目 前 这 个 标志 位 未 被 使 用 


unsigned unexpected eof:1; 





1 时 表示 延迟 建立 


TCP 连 接 ， 也 就 是 说 ， 经 过 


TCP 三 次 握手 后 并 不 建立 连接 ， 而 是 要 等 到 真正 收 到 数据 包 后 才 会 建立 


TCP 连 接 


*/ 





unsigned deferred accept:1; 
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kqueue 和 


aio 事 件 驱 动机 制 有 关 ， 不 再 详 述 


unsigned pending eof:1; 


#if ! (NGX THREADS) 





// 标志 位 ， 如 果 为 


1， 则 表示 在 处 理 





post 事 件 时 ， 当 前 事件 已 经 准备 就 绪 


unsigned posted ready:1; 


#endif 


epoll 事 件 驱 动机 制 下 表示 一 次 尽 可 能 多 地 建立 


TCP 连 接 ， 它 与 


multi accept 配置 项 对 应 ， 实 现 原理 参见 


9.8.1 节 


unsigned available:1; 





// 这 个 事件 发 生 时 的 处 理 方法 ， 每 个 事件 消费 模块 都 会 


[HHNDNDNDND DID D 








wy 


*/ 


重新 实现 它 


tp: // WW | 1 NUxpor obe. con 


ngx event handler pt handler; 





#if (NGX HAVE AIO) 


#if (NGX HAVE IOCP) 








// Windows 系 统 下 的 一 种 事件 驱动 模型 ， 这 里 不 再 详 述 


ngx event ovlp t ovilp; 


#else 


// Linux aio 机 制 中 定义 的 结构 体 ， 在 


9.9 节 中 会 详细 说 明 它 


Struct alocp aiocb; 


#endif 


#endif 


/7 秘 填 





epoll 事 件 驱 动 方式 不 使 用 


indqex， 所 以 这 里 不 再 说 明 


ngx uint 七 index; 


// 可 用 于 记录 
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error 1og 日 志 的 


ngx 1og 七 对 象 


ngx log 七 *log; 


ngx rbtree node t timer; 





// 标志 位 ， 为 





1 时 表示 当前 事件 已 经 关闭 ， 


epol1 模 块 没有 使 用 它 


unsigned closed:1; 


// 该 标志 位 目前 无 实际 意义 


unsigned channel:1; 


// 该 标志 位 目前 无 实际 意义 


unsigned resolver:1; 





/*post 事 件 将 会 构成 一 个 队列 再 统一 处 理 ， 这 个 队列 以 


next 和 
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prev 作 为 链表 指针 ， 以 此 构成 一 个 简易 的 双向 链表 ， 其 中 


next 指 向 后 一 个 事件 的 地 址 ， 





prev 指 向 前 一 个 事件 的 地 址 


ngx event 七 *next; 


ngx event t **prev; 


*/ 

















每 一 个 事件 最 核心 的 部 分 是 handler 回 调 方法 ， 它 将 由 每 一 个 事件 消费 模块 实现 ， 以 此 决定 这 个 事件 究竟 如 何 “ 消 费 ”， 








typedef void (*ngx event handler Pt) (ngx event t *ev); 




















所 有 的 Nginx 模 块 只 要 处 理事 件 就 必然 要 设置 handler 回 调 方法 ， 后 续 章 节 会 有 许多 handler 回 调 方法 的 例子 ， 这 里 不 再 








下 面 开 始 说 明 操作 事件 的 方法 。 


事件 是 不 需要 创建 的 ， 





因为 Nginx 在 启动 时 已 经 在 ngx_cycle_ t 的 read_events 成 员 中 预 分 配 了 所 有 的 读 事件 ， 并 在 write 








先 看 一 下 ngx handle read event 方 法 的 原型 : 





ngx_ int t ngx handle read event (ngx event 七 *rev, ngx uint t flags); 











ngx_handle read_event 方 法 会 将 读 事件 添加 到 事件 引 











动 模块 中 ， 这 样 该 事件 对 应 的 TCP 连 接 上 一 旦 日 








8 现 可 读 事 件 〈 丸 


下 面 看 一 下 ngx_handle read_event 的 参数 和 返回 值 。 参 数 rev 是 要 操作 的 事件 ，fags 将 会 指定 事件 的 驱动 方式 。 对 于 “ 


再 看 一 下 ngx handle write event 方 法 的 原型 : 





ngx_int t ngx handle write event (ngx event t *wev, size t lowat); 














日 


ngx_handle write_event 方 法 会 将 写 事件 添加 到 事件 驱动 模块 中 。wev 





下 

















要 操作 的 事件 ， 而 lowat 则 表示 只 有 当 连 接 对 








一 般 在 向 epoll 中 添加 可 读 或 者 可 写 事 件 时 ， 都 是 使 用 ngx handle read event 或 者 ngx handle write _event 方 法 的 。 对 于 


#define ngx_aqd_event 


ngx_event actions.add #define ngx del event 





ngx_ event actions.del #define ngx adqd conn 


ngx_event actions.add 
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9.3 ”Neginx 连 接 的 定义 


作为 Web 服 务 器 ， 每 一 个 用 户 请 求 至 少 对 应 着 一 个 TCP 连 接 ， 为 了 及 时 处 理 这 个 连接 ， 
至 少 需要 一 个 读 事件 和 一 个 写 事 件 ， 使 得 epoll 可 以 有 效 地 根据 触发 的 事件 调度 相应 模块 读 取 
请 求 或 者 发 送 啊 应 。 因 此 ，Nginx 中 定义 了 基本 的 数据 结构 ngx_connection t 来 表示 连接 ， 这 
个 连接 表示 是 客户 端 主 动 发 起 的 、Nginx 服 务 器 被 动 接受 的 TCP 连 接 ， 我 们 可 以 简单 称 其 为 被 
动 连接 。 同 时 ， 在 有 些 请 求 的 处 理 过 程 中 ，Nsginx 会 试图 主动 向 其 他 上 游 服 务 器 建立 连接 ， 
并 以 此 连接 与 上 游 服务 器 通信 ， 因 此 ， 这 样 的 连接 与 ngx_connection {t 又 是 不 同 的 ，Nsginx 定 
义 了 ngx_peer_connection t 结 构 体 来 表示 主动 连接 ， 当 然 ，ngx_peer_connection t 主 动 连接 是 
以 ngx_connection 结构 体 为 基础 实现 的 。 本 节 将 说 明 这 两 种 连接 中 各 字段 的 意义 ， 同 时 需要 
注意 的 是 ， 这 两 种 连接 都 不 可 以 随意 创建 ， 必 须 从 连接 池 中 获取 ， 在 9.3.3 节 中 会 说 明 连接 池 
的 用 法 。 














9.3.1 ”被动 连接 





本 章 中 未 加 修饰 提 到 的 “连接 ”都 是 指 客 户 端 发 起 的 、 服 务 器 被 动 接受 的 连接 ， 这 样 的 连 
接 都 是 使 用 ngx_ connection t 结 构 体 表示 的 ， 其 定义 如 下 。 





typedef struct ngx connection s ngx connection t; struct ngx connection s { 
/* 连 接 未 使 用 时 ， 

data 成 员 用 于 充当 连接 池 中 空闲 连接 链表 中 的 

next 指 针 。 当 连接 被 使 用 时 ， 

data 的 意义 由 使 用 它 的 


Nginx 模 块 而 定 ， 如 在 
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HTTP 框 架 中 ， 


data 指 向 


ngx_http_request_t 请 求 


void *data; 


// 连接 对 应 的 读 事 





个 


件 


ngx event t *read; 


// 连接 对 应 的 写 事件 


ngx event t *write; 


// 套 接 字 自 本 


ngx socket t fq; 


// 直接 接收 网 络 字符 流 的 方法 


ngx_recv pt recv; 


// 直接 发 送 网 络 字符 流 的 方法 


ngx_send pt send; 
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ngx_chain 七 链表 为 参数 来 接收 网 络 字符 流 的 方法 


ngx recv chain pt recv chain; 


// 以 


ngx_chain 七 链表 为 参数 来 发 送 网 络 字符 流 的 方法 


ngx send chain pt send chain; 


/* 这 个 连接 对 应 的 


ngx listening 七 监听 对 象 ， 此 连接 由 





listening 监 听 端 口 的 事件 建立 
*/ 
ngx listening 七 *listening; 


// 这 个 连接 上 已 经 发 送出 去 的 字 节 数 


off 七 sent; 
// 可 以 记录 日 志 的 


ngx_ 1og 七 对 象 


ngx log 七 *1og7 


/* 内 存 池 。 一 般 在 
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accept 一 个 新 连接 时 ， 会 创建 一 个 内 存 池 ， 而 在 这 个 连接 结束 时 会 销毁 内 存 池 。 注 意 ， 这 里 所 说 的 连接 是 指 成 功 建立 的 
TCP 连 接 ， 所 有 的 
ngx_connection 七 结构 体 都 是 预 分 配 的 。 这 个 内 存 池 的 大 小 将 由 上 面 的 
1istening 监 听 对 象 中 的 
pool size 成 员 决 定 
*/ 
ngx pool t *pool; 
// 连接 客户 端的 


sockaddr 结 构 体 


struct sockaddr *sockaddr; 


// sockaddr 结 构 体 的 长 度 


socklen t socklen; 
// 连接 客户 端 字 符 串 形式 的 


IP 地 址 


ngx str t addr text; 
/* 本 机 的 监听 端口 对 应 的 


sockagddr 结 构 体 ， 也 就 是 
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sockaddr 成 员 


人 


struct sockaddr *local sockaddr; 


/* 用 于 接收 、 缓 存 客户 端 发 来 的 字符 流 ， 每 个 事件 消费 模块 可 自由 决定 从 连接 池 中 分 配 多 大 的 空间 给 


buffer 这 个 接收 缓存 字段 。 例 如 ， 在 


HTTP 模 块 中 ， 它 的 大 小 决定 于 





client header buffer size 配 置 项 








8 
ngx _ buf t xbuffer; 
/* 该 字段 用 来 将 当前 连接 以 双向 链表 元 素 的 形式 添加 到 
ngx_cycle 七 核心 结构 体 的 
reusable connections queue 双 向 链表 中 ， 表 示 可 以 重用 的 连接 
Sy 


ngx queue 七 queue; 

/* 连 接 使 用 次 数 。 
ngx_connection 结构 体 每 次 建立 一 条 来 自 客户 端的 连接 ， 或 者 用 于 主动 向 后 端 服务 器 发 起 连接 时 ( 
ngx peer connection 七 也 使 用 它 ) ， 
number 都 会 加 


1L*y 
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// 处 理 的 请 求 次 数 


ngx uint t requests; 


/* 缓 存 中 的 业务 类 型 。 任 何事 件 消 费 模块 都 可 以 自 定义 需要 的 标志 位 。 这 个 


buffered 字 段 有 


8 位 ， 最 多 可 以 同时 表示 


8 个 不 同 的 业务 。 第 三 方 模块 在 自 定义 


buffered 标 志 位 时 注意 不 要 与 可 能 使 用 的 模块 定义 的 标志 位 冲突 。 目 前 


openssl 模 块 定义 了 一 个 标志 位 : 





#define NGX SSL BUFFERED 0x01 











HTTP 官 方 模块 定义 了 以 下 标志 位 : 





































































































#define NGX HTTP LOWLEVEL BUFFERED 0xf£0 
define NGX HTTP WRITE BUFFERED 0x10 
define NGX HTTP GZIP BUFFERED 0x20 
define NGX HTTP SSI BUFFERED 0x01 
define NGX HTTP SUB BUFFERED 0x02 
#define NGX HTTP COPY BUFFERED 0x04 
#define NGX HTTP IMAGE BUFFERED 0x08 同 时 ， 对 于 
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HTTP 模 块 而 言 ， 


buffered 的 低 


4 位 要 慎 用 ， 在 实际 发 送 响 应 的 


ngx http write filter module 过 滤 模 块 中 ， 低 





4 位 标志 位 为 


1 则 意味 着 


Nginx 会 一 直 认 为 有 


HTTP 模 块 还 需要 处 理 这 个 请 求 ， 必 须 等 待 


HTTP 模 块 将 低 


0 才 会 正常 结束 请 求 。 检 查 低 


4 位 的 宏 如 下 : 

















#define NGX LOWLEVEL BUFFERED Ox0f 
yA 
unsigned buffered:8; 
/* 本 连接 记录 日 志 时 的 级 别 ， 它 占用 了 
3 位 ， 取 值 范 围 是 
0~7， 但 实际 上 目前 只 定义 了 


5 个 值 ， 由 
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ngx_connection 1og _ error e 枚 举 表示 ， 如 下 : 


typedef enum { 











NGX ERROR ALERT = 0, 





NGX_ ERROR ERR, 











NGX_ ERROR INFO, 














NGX ERROR IGNORE ECONNRESET, 



































NGX ERROR IGNORE EINVAL 








} ngx connection log error e; 


Sy 


unsigned log error:3; 


/* 标 志 位 ， 为 


1 时 表示 独立 的 连接 ， 如 从 客户 端 发 起 的 连接 ; 为 


0 时 表示 依靠 其 他 连接 的 行为 而 建立 起 来 的 非 独 立 连接 ， 如 使 用 


upstream 机 制 向 后 端 服务 器 建立 起 来 的 连接 


Wy 


unsigned single connection:1; 


// 标志 位 ， 为 


1 时 表示 不 期 待 字符 流 结束 ， 目 前 无 意义 


由 
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// 标志 位 ， 为 


1 时 表示 连接 已 经 超时 


unsigned timedout:1; 
// 标志 位 ， 为 


1 时 表示 连接 处 理 过 程 中 出 现 错误 


unsigned error:1; 


1 时 表示 连接 已 经 销毁 。 这 里 的 连接 指 是 的 

TCP 连 接 ， 而 不 是 

ngx_connection 七 结构 体 。 当 

destroyed 为 

Ls 

ngx_connection t 结 构 体 仍然 存在 ,但 其 对 应 的 套 接 字 、 内 存 池 等 已 经 不 可 用 
*/ 


unsigned destroyed:1; 


1 时 表示 连接 处 于 空闲 状态 ， 如 


keepalive 请 求 中 两 次 请 求 之 间 的 状态 
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unsigned idle:1; 


// 标志 位 ， 为 


1 时 表示 连接 可 重用 ， 它 与 上 面 的 





queue 字 段 是 对 应 使 用 的 


unsigned reusable:1; 


// 标志 位 ， 为 


1 时 表示 连接 关闭 


unsigned close:1; 


// 标志 位 ， 为 


1 时 表示 正在 将 文件 中 的 数据 发 往 连 接 的 另 一 端 


unsigned sendfile:1; 


/* 标 志 位 ， 如 果 为 





1， 则 表示 只 有 在 连接 套 接 字 对 应 的 发 送 缓冲 区 必须 满足 最 低 设置 的 大 小 赋值 时 ， 事 件 驱 动 模块 才 会 分 发 该 事件 。 这 与 上 文 介绍 过 的 


ngx handle write event 方 法 中 的 





lowat 参 数 是 对 应 的 


性 
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/* 标 志 位 ， 表 示 如 何 使 用 


TCP 的 


nodelay 特 性 。 它 的 取 值 范围 是 下 面 这 个 枚 举 类 型 


ngx connection tcp nodelay e: 


typedef enum { 











NGX TCP NODELAY UNSET = 0, 





NGX_ TCP NODELAY SET, 











NGX TCP NODELAY DISABLED 








} ngx connection tcp nodelay e; 


yy 


unsigned tcp nodelay:2; 


/* 标 志 位 ， 表 示 如 何 使 用 


TCP 的 


nopush 特 性 。 它 的 取 值 范围 是 下 面 这 个 枚 举 类 型 


ngx connection tcp nopush e: 


typedef enum { 


NGX TCP NOPUSH UNSET = 0, 





NGX_ TCP NOPUSH SET, 
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NGX TCP NOPUSH DISABLED 





} ngx connection tcp nopush e; 


*/ 


unsigned tcp nopush:2; 

















#if (NGX HAVE AIO SENDFILE 


// 标志 位 ， 为 


1 时 表示 使 用 异步 


I/O 的 方式 将 磁盘 上 文件 发 送 给 网 络 连接 的 另 一 端 


unsigned aio sendfile:1; 


// 使 用 异步 


I/O 方 式 发 送 的 文件 ， 


busy_sendfile 缓 冲 区 保存 待 发 送 文件 的 信息 


ngx buf t *busy sendfile; 


#endif 





链表 中 的 recv、send、recv_chain、send_chain 这 4 个 关于 接收 、 发 送 网 络 字符 流 的 方法 原型 定义 如 下 。 
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typedef ssize t (*ngx recv pt) (ngx connection t c, u char buf, size t size); typedef ssize t (*ngx recv chain pt) (ngx_connection t c, ngx chain t in); 七 











这 4 个 成 员 以 方法 指针 的 形式 出 现 ， 说 明 每 个 连接 都 可 以 采用 不 同 的 接收 方法 ， 每 个 事件 消费 模块 都 可 以 灵活 地 决 名 


9.3.2 ”主动 连接 


作为 Web 服 务 器 ，Nginx 也 需要 问 其 他 服务 器 主动 发 起 连接 ， 当 然 ， 这 样 的 连接 与 上 一 节 介绍 的 被 动 连接 是 不 同 的 ， 





typedef struct ngx peer connection s ngx peer connection t; // 当 使 用 长 连接 与 上 游 服务 器 通信 时 ) 可 通过 该 方 法 由 连接 池 中 获取 一 个 新 连接 
typedef ngx int t (*ngx event get peer pt) (ngx peer connection t pc,void data); // 当 使 用 长 连接 与 上 游 服务 器 通信 时 a 通过 该 方法 将 使 用 完毕 的 连 4 


typedef void (*ngx event free peer pt) (ngx peer connection 七 pc void data,ngx uint t state); struct ngx peer connection s { 
/* 一 个 主动 连接 实际 上 也 需要 

ngx_connection t 结 构 体 中 的 大 部 分 成 员 》 并 且 出 名 重用 的 考虑 而 定义 J 

connection 成 , 员 
ngx_connection 七 *connection; 
// 远 端 服务 器 的 


socket 地 址 


struct sockaddr *sockaddr; 


// sockaddr 地 址 的 长 度 
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// 远 端 服务 器 的 名 称 


ngx_str 七 *name; 


/* 表 示 在 连接 一 个 远 端 服务 器 时 ， 当 前 连接 出 现 异 常 失败 后 可 以 重 试 的 次 数 ， 也 就 是 允许 的 最 多 失败 次 数 





*/ 
ngx uint t tries; 
// 获取 连接 的 方法 ， 如 果 使 用 长 连接 构成 的 连接 池 ， 那 么 必须 要 实现 


get 方 法 


ngx event get peer pt get; 
// 与 


get 方 法 对 应 的 释放 连接 的 方法 


ngx event free peer pt free; 
7 个 

data 指 针 仅 用 于 和 上 面 的 

get、 

free 方 法 配合 传递 参数 ， 它 的 具体 含义 与 实现 

get 方 法 、 

free 方 法 的 模块 相关 ， 可 参照 

ngx event get peer pt 和 

ngx event free peer pt 方法 原型 中 的 

data 参 数 

*/ 

void *data; 


// 本 机 地 址 信息 
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ngx addr t *local; 


// 套 接 字 的 接收 缓冲 区 大 小 


int rcvbuf; 


// 记录 日 志 的 


ngx log 七 对 象 


ngx log 七 *log; 


// 标志 位 ， 为 


1 时 表示 上 面 的 


connection 连接 过 经 缓存 


unsigned cached:1; 


总 


.3.1 节 下 


ngx_connection 七 里 的 


log error 意 义 是 相同 的 ， 区 别 在 于 这 里 的 


1og_error 只 有 两 位 ) 只 能 表达 


4 种 错误 ， 


NGX_ERROR_IGNORE EINVAL 错 误 无 法 表达 


4 


unsigned log error:2; 








ngx_peer_connection t 也 有 一 个 ngx_connection t 类 型 的 成 员 ， 怎 么 理解 这 两 个 结构 体 之 间 的 关系 呢 ? 所 有 的 事件 消费 
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9.3.3 ”ngx_connection ft 连接 池 





Nginx 在 接受 客户 端的 连接 时 ， 所 使 用 的 ngx_connection t 结 构 体 都 是 在 启动 阶段 就 预 分 配 好 的 ， 使 用 时 从 连接 池 中 球 


从 图 9-1 中 可 以 看 出 ， 在 ngx_cycle t 中 的 connections 和 free_connections 这 两 个 成 员 构 成 了 一 个 连接 池 ， 其 中 connections 











图 9-1 中 还 显示 了 事件 池 ，Nginx 认 为 每 一 个 连接 一 定 至 少 需 要 一 个 读 事件 和 一 个 写 事件 ， 有 多 少 连 接 就 分 配 多 少 个 i 























在 使 用 连接 池 时 ，Nginx 也 封装 了 两 个 方法 ， 见 表 9-1。 








如 果 我 们 开发 的 模块 直接 使 用 了 连接 池 ， 那 么 就 可 以 用 这 两 个 方法 来 获取 、 释 放 ngx_connection_t 结 构 体 。 
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TTT 加 TITTT 
| 


free_connections 
+free_connection n 
+reusable _connections queue :ngx queue s 
: ngx array _t 


预 分 配 的 


| 

| 

> | 
connection _n 个 连接 
| 

| 


+open files: ngx list t 

| +shared memory: ngx_list { 
| | +connection mn 
| +files mn 


TITT 恒 TTTT pee 
read events 


write_events 


| +old cycle 
| +conf file 


预 分 配 的 


connection _n 个 读 事 件 


+ngx_ master process cycle() 
国 国 国 国 一 也 面 醒 本 大 +ngx_single_process cycle() 
I +ngx_ start worker processes() 

+ngx start cache manager processes() 


预 分 配 的 +ngx_pass open channel() 
connection Hn 个 妇 究 御 ngx_ signal worker processes() 


ngx_reap children () 
ngx_master process exit() 
+ngx worker process cycle() 
+ngx worker process init () 
+ngx_ worker process exit() 
+ngx cache manager process cycle() 
+ngx process events and timers() 


在 connections 指 问 的 连接 池 
中 ， 每 个 连接 所 需要 的 读 / 写 
事件 都 以 相同 的 数组 序号 对 


应 着 read_events、Wwrite ， eo 
读 / 写 事件 数组 ， 相 同 序号 

这 3 个 数组 中 的 元 素 是 配合 使 
用 的 





图 9-1 ngx_connection_t 连 接 池 示意 图 


表 9-1 连接 池 的 使 用 方法 


连接 池 操 作 方 法 名 执行 意义 
ngx connection t *ngx get connection s 是 ; re 接 的 套 接 字句 柄 ,| 从 连接 池 中 获取 一 个 ngx_connection t 
(ngx_ socket ts, ngx log t *log) log 则 ce 日 志 的 对 象 结构 体 ， 同 时 获取 相应 的 读 / 写 事件 
void ngx_ free_connection TE: 人 eA 
i c 是 需要 回收 的 连接 将 这 个 连接 回收 到 连接 池 中 





(ngx_ connection t *c) 
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9.4 ngx events_ module 核心 模块 


ngx_events_module 模 块 是 一 个 核心 模块 ， 它 定义 了 一 类 新 模块 : 事件 模块 。 它 的 功能 如 
下 : 定义 新 的 事件 类 型 ， 并 定义 每 个 事件 模块 都 需要 实现 的 negx_event_ module t 接 口 《〈 人 参见 
9.1.1 节 ) ， 还 需要 管理 这 些 事件 模块 生成 的 配置 项 结构 体 ， 并 解析 事件 类 配置 项 ， 当 然 ， 在 
解析 配置 项 时 会 调用 其 在 ngx command 堵 组 中 定义 的 回调 方法 。 这 些 过 程 在 下 文中 都 会 介 
绍 ， 不 过 ， 首 先 还 是 看 一 下 ngx events module 模 块 的 定义 。 








就 像 在 第 3 章 中 我 们 曾经 做 过 的 一 样 ， 定 义 一 个 Nginx 模 块 就 是 在 实现 ngx_ modult_ 结构 
体 。 这 里 需要 先 定 义 好 ngx_command t《〈 决 定 这 个 模块 如 何 处 理 目 己 感 兴趣 的 配置 项 ) 数 
组 ， 因 为 任何 模块 都 是 以 配置 项 来 定制 功能 的 。ngx_events_commands 数 组 决定 了 
ngx_events_module 模 块 是 如 何 定制 其 功能 的 ， 代 码 如 下 。 





static ngx command t ngx events commands[] = { 
{ ngx string("events"), 

NGX MAIN CONF|NGX CONF BLOCK|NGX CONF NOARGS, 

ngx events block, 

0, 

0， 
NULL }, 
ngx null command 








可 以 看 到 ，ngx_events_module 模 块 只 对 一 个 块 配 置 项 感 兴趣 ， 也 就 是 nginx.conf 中 必须 有 
的 events{...} 配 置 项 。 注 意 ， 这 里 暂时 先 不 要 关心 ngx events_ block 方法 是 如 何 处 理 这 个 配置 
项 的 。 


作为 核心 模块 ，ngx_events_module 还 需要 实现 核心 模块 的 共同 接口 ngx_core_module t， 
如 下 所 示 。 





static ngx core module t ngx events module ctx = { 
ngx string("events"), 
NULL, 














NULL 











可 以 看 到 ，ngx events_module_ctx 实 现 的 接口 只 是 定义 了 模块 名 字 而 已 ， 
ngx_core_module t 接 口中 定义 的 create_conf 方 法 和 init_conf 方 法 都 没有 实现 (NULL 空 指针 即 
为 不 实现 ) ， 为 什么 呢 ? 这 是 因为 ngx_events_module 模 块 并 不 会 解析 配置 项 的 参数 ， 只 是 在 
出 现 events 配 置 项 后 会 调用 各 事件 模块 去 解析 events{...} 块 内 的 配置 项 ， 自 然 就 不 需要 实现 
create_conf 方 法 来 创建 存储 配置 项 参数 的 结构 体 ， 也 不 需要 实现 init_conf 方 法 处 理解 析出 的 配 
置 项 。 





最 后 看 一 下 ngx_events_module 模 块 的 定义 代码 如 下 。 





ngx module t ngx events module = { 
NGX MODULE V1, 











&ngx events module ctx, /* module context 
ngx events commands, module directives 
NGX CORE MODULE, module type 

NULL, init master 

NULL, init module 

NULL, init process 
NULL, init thread 

NULL, exit thread 

NULL, exit process 
NULL, exit master */ 


NGX MODULE V1 PADDING 











可 见 ， 除 了 对 events 配 置 项 的 解析 外 ， 该 模块 没有 做 其 他 任何 事情 。 下 面 开始 介绍 在 解 
析 events 配 置 块 时 ，ngx_events_block 方 法 做 了 些 什么 。 


9.4.1 如 何 管理 所 有 事件 模块 的 配置 项 


上 文 说 过 ， 每 一 个 事件 模块 都 必须 实现 ngx_event_ module t 接 口 ， 这 个 接口 中 允许 每 个 事 
件 模 块 建 立 目 己 的 配置 项 结构 体 ， 用 于 存储 感 兴趣 的 配置 项 在 nginx.conf 中 对 应 的 参数 。 
ngx_event_module_t 中 的 create_conf 方 法 就 是 用 于 创建 这 个 结构 体 的 方法 ， 事 件 模 块 只 需要 在 
这 个 方法 中 分 配 内 存 即 可 ， 但 这 个 内 存 指针 是 如 何 由 ngx_events_module 模 块 管理 的 昵 ?下 面 
来 看 一 下 这 些 事件 模块 的 配置 项 指针 是 如 何 被 存放 的 ， 如 图 9-2 所 示 。 








每 一 个 事件 模块 产生 的 配置 结构 体 指 针 都 会 被 放 到 ngx_events _ module 模块 创建 的 指针 数 
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组 中 ， 可 这 个 指针 数组 又 存放 到 哪里 呢 ? 看 一 下 ngx_cycle t 核 心 结构 体 中 的 conf_ctx 成 员 ， 它 
指向 一 个 指针 数组 ， 而 这 个 指针 数组 中 就 依次 存放 着 所 有 的 Nginx 模 块 关 于 配置 项 方面 的 指 
针 。 在 默认 的 编译 顺序 下 ， 从 ngx modules.c 文 件 中 可 以 看 到 ngx_events_ module 模 块 是 在 
ngx_modules 数 组 中 的 第 4 个 位 置 ， 因 此 ， 所 有 进程 的 conf ctx 数 组 的 第 4 个 指针 就 保存 着 上 面 
说 过 的 ngx_events_module 模 块 创 建 的 指针 数组 。 解 释 是 不 是 有 点 绕 ? 再 回顾 一 下 ngx_cycle { 
结构 体 中 的 conf ctx 的 定义 : 





void eontf CE 


为 什么 上 面 代码 中 有 4 个 *? 因为 它 首 先 指 癌 一 个 存放 指针 的 数组 ， 这 个 数组 中 的 指针 成 
员 同 时 又 指 问 了 另外 一 个 存放 指针 的 数组 ， 所 以 是 4 个 *。 看 到 conf ctx 的 奥秘 了 吧 。 只 有 拥 
有 了 这 个 conf_ctx， 才 可 以 看 到 任意 一 个 模块 在 create_conf 中 产生 的 结构 体 指针 。 同 理 ， 
HTTP 模 块 和 mail 模 块 也 是 这 样 做 的 ， 这 些 模 块 的 通用 接口 中 也 有 create_conf 方 法 ， 其 产生 的 
指针 会 以 相似 的 方式 存放 。 


每 一 个 事件 模块 如 何 获取 和 它 在 create_conf 中 分 配 的 结构 体 的 指针 呢 ? ngx_events_module 
定义 了 一 个 简单 的 宏 来 完成 这 个 功能 代码 ， 如 下 。 


#define ngx event get conf (conf ctx,module) \ 
(*(ngx get conf (conf ctx, ngx events module))) [module.ctx index]; 








ngx_get_conf 也 是 一 个 宏 ， 它 用 来 获取 图 9-1 中 第 一 个 数组 中 的 指针 ， 如 下 所 示 。 


#define ngx get conf (conf ctx, module) conf ctx[module.index] 





此 ， 调 用 ngx event get conf 时 只 需要 在 第 1 个 参数 中 传 入 ngx_cycle t 中 的 conf ctx 成 
员 ， 在 第 2 个 参数 中 传 入 自己 的 模块 名 ， 就 可 以 获取 配置 项 结构 体 的 指针 。 详 细 内 容 可 参见 
9.6.3 节 中 使 用 ngx epoll module 的 ngx epoll init 方 法 获取 配置 项 的 例子 。 
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ngx cycle 1 


所 有 核心 模块 的 配置 结构 体 指针 


+free connections 
+free connection n 
+ reusable connections _ queue :ngx queue s 


: ngx array t 
+open files: ngx list t 
+ shared memory: ngx list 【1 
+connection_n 


第 4 个 模块 是 ngx_events_ made 
模块 ， 因 此 ，conf_ctx 数 组 中 第 4 
位 存储 着 模块 的 配置 项 指针 ， 在 
这 里 这 个 指针 定义 为 指 问 男 一 





: +files _n 
数组 + connections 
所 有 事件 模块 的 配置 结构 体 指针 + read events 


+ write_ events 
一 sa 

+conf file 
+ conf prefix 
十 prefix 
+lock file 
+ hostname 
+ngx master process cycle () 
+ngx single_ process _cycle () 
+ngx start worker processes () 
+ngx start _ cache manager processes() 
+ngx pass_open channel () 
+ngx signal worker processes () 
+ngx reap _children () 


事件 模块 1 中 create_conf 
方法 创建 的 结构 体 


事件 模块 2 中 create_conf 





方法 创建 的 结构 体 +ngx master process exit () 
+ ngx worker process_ cycle () 
ngx worker process init () 
事件 模块 3 中 create_conf + ngx worker process exit () 
方法 创建 的 结构 体 ngx cache manager process cycle () 





ngx process events and timers () 


事件 模块 4 中 create_conf 


方法 创建 的 结构 体 





图 9-2 所 有 事件 模块 配置 项 结构 体 的 指针 是 如 何 管理 的 


9.4.2 管理 事件 模块 
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上 文 说 到 ， 配 置 项 结构 体 指针 的 保存 都 是 在 ngx_events_block 方 法 中 进行 的 。 下 面 再 来 看 
一 下 这 个 方法 执行 的 流程 图 ， 如 图 9-3 所 示 。 


1 ) 初始 化 所 有 事件 模块 的 ctx _index 序号 





2 ) 分 配 指针 数组 ,存储 所 有 事件 模块 生成 的 配置 项 结构 体 指针 





EE 调用 所 有 小 件 模块 HY create con 方法 





4 ) 为 所 有 事件 模块 解析 neinx. conf 邵 置 文件 


5 ) 调用 上 有 所 有 事件 模块 的 init _conf 方法 





@ 


图 9-3 ”ngx_events_module 核 心 模块 如 何 加 载 事件 模块 


下 面 简要 描述 一 下 这 5 个 步 又 。 


1) 首先 初始 化 所 有 事件 模块 的 ctx index 成 员 。 这 里 要 先 回 顾 一 下 ngx module t 模 块 接 口 
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的 定义 ， 如 下 所 示 。 





struct ngx module s { 
ngx uint t ctx index; 
ngx uint t index; 








这 里 的 index 是 所 有 模块 在 ngx modules.c 文 件 的 ngx modules 数 组 中 的 序号 ， 它 与 
ngx_ modules 数 组 中 所 有 模块 的 顺序 是 一 臻 的 。 什 么 时 候 初 始 化 这 个 index 呢 ? 局 动 Nginx 后 ， 
在 调用 第 8 章 中 介绍 过 的 ngx init_ cycle 方法 前 就 会 进行 ， 代 码 如 下 。 





ngx max module = 0; 
for (i = 0; ngx modules[i]; i++) { 
ngx modules[i]->index = ngx max modulett+; 


} 








其 中 ，ngx_max_module 是 Nginx 模 块 的 总 个 数 。 注 意 ， 本 书 前 文 曾 多 次 提 到 过 ，Nginx 各 
模块 在 ngx_modules 数 组 中 的 顺序 是 很 重要 的 ， 依 靠 index 成 员 ， 每 一 个 模块 才 可 以 把 自己 的 
位 置 与 其 他 模块 的 位 置 进行 比较 ， 并 以 此 决定 行为 。 但 是 ，Nginx 同 时 又 允许 再 次 定义 子 类 
型 ， 如 事件 类 型 、HITP 类 型 、mail 类 型 ， 那 同一 类 型 的 模块 间 又 如 何 区 分 顺序 呢 《〈 依 靠 
index 当 然 可 以 区 分 顺序 ， 但 index 是 针对 所 有 模块 的 ， 这 样 效率 太 差 ) ? 这 就 得 依靠 ctx_index 
成 员 了 。ctx index 表 明了 模块 在 相同 类 型 模块 中 的 顺序 。 














此 ，ngx events_block 方 法 的 第 一 步 束 是 初始 化 所 有 事件 模块 的 ctx index 成 员 ， 这 会 决 
定 以 后 加 载 各 事件 模块 的 顺序 。 其 代码 非常 简单 ， 如 下 所 示 。 





ngx event max module = 0; 
for (i = 0; ngx modules[i]; i++) { 
if (ngx modules[i]->type != NGX EVENT MODULE) { 
continue; 
} 


ngx modules[i]->ctx index = ngx event max modulett+; 

















} 





其 中 ，ngx event max module 是 编译 进 Nginx 的 所 有 事件 模块 的 总 个 数 。 
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2) 分 配 9.4.1 节 中 介绍 的 指针 数组 ， 不 再 详 述 。 


3) 依次 调用 所 有 事件 模块 通用 接口 ngx_event_ module t 中 的 create_conf 方 法 ， 当 然 ， 产 
生 的 结构 体 的 指针 保存 在 上 面 的 指针 数组 中 。 





4) 针对 所 有 事件 类 型 的 模块 解析 配置 项 。 这 时 ， 每 个 事件 模块 定义 的 ngx_command t 决 
定 了 配置 项 的 解析 方法 ， 如 果 在 nginx.conf 中 发 现 相应 的 配置 项 ， 束 会 回调 各 事件 模块 定义 的 
方法 。 


5) 解析 完 配 置 项 后 ， 依 次 调用 所 有 事件 模块 通用 接口 ngx_event_module t 中 的 init_conf 方 
法 ， 实 现 了 这 个 方法 的 事件 模块 可 以 在 此 做 一 些 配置 参数 的 整合 工作 。 








以 上 束 是 ngx_ events_module 模 块 的 核心 工作 流程 。 对 于 事件 驱动 机 制 ， 更 多 的 工作 是 在 
ngx_event_core_ module 模 块 中 进行 的 ， 下 面 继 续 看 一 下 这 个 模块 做 了 些 什么 。 
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9.5 ngx event core module 事 件 模块 





ngx_event_core_module 模 块 是 一 个 事件 类 型 的 模块 ， 它 在 所 有 事件 模块 中 的 顺序 是 第 一 
位 (configure 执 行 时 必须 把 它 放 在 其 他 事件 模块 之 前 〉)。 这 就 保证 了 它 会 先 于 其 他 事件 模块 
执行 ， 由 此 它 选择 事件 驱动 机 制 的 任务 才 可 以 完成 。 





ngx_event_core_module 模 块 要 完成 哪些 任务 呢 ?” 它 会 创建 9.3 节 中 介绍 的 连接 池 (包括 读 / 
写 事 件 ) ， 同 时 会 决定 究竟 使 用 哪些 事件 驱动 机 制 ， 以 及 初始 化 将 要 使 用 的 事件 模块 。 


下 面 先 来 看 一 下 ngx event core _ module 模块 对 哪些 配置 项 感 兴趣 。 该 模块 定义 了 
ngx_event_ core_commands 数 组 处 理 其 感 兴趣 的 7 个 配置 项 ， 以 下 进行 简要 说 明 。 





static ngx command t ngx event _ core commands[] = { 


/* 连 接 池 的 大 小 ， 也 就 是 每 个 





worker 进 程 中 支持 的 


TCP 最 大 连接 数 ， 它 与 下 面 的 


connections 配 置 项 的 意义 是 重复 的 ， 可 参照 





9.3.3 节 理解 连接 池 的 概念 


Wp 
{ ngx string("worker connections"), 
NGX EVENT CONF|NGX CONF TAKE1， 
ngx event connections, 

















0, 
NULL }, 
// 连接 池 的 大 小 ， 与 


worker_connections 配 置 项 意义 相同 
{ ngx string("connections"), 


NGX_ EVENT CONF|INGX CONF TRAKE1， 
ngx event connections, 

















0， 
0， 
NULL }, 
// 确定 选择 哪 一 个 事件 模块 作为 事件 驱动 机 制 
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NGX _ EVENT CONF|NGX CONF TAKE1， 
ngx event use, 
0, 
0, 
NULL }, 
/* 对 应 于 


9.2 节 中 提 到 的 事件 定义 的 

available 字 上段。 对 于 

epoll 事 件 驱 动 模式 来 说 ， 意 味 着 在 接收 到 一 个 新 连接 事件 时 ， 调 用 
accept 以 尽 可 能 多 地 接收 连接 


wf 

{ ngx string("multi accept"), 
NGX EVENT CONF|NGX CONF FLAG, 
ngx conf set flag slot, 
0, 
offsetof (ngx event conf t, multi accept), 
NULL }, 

// 确定 是 否 使 用 

















accept mutex 负 载 均衡 锁 ， 默 认为 开启 


{ ngx _ String("accept mutex"), 
NGX_ EVENT CONF|NGX CONF FLAG, 
ngx conf set flag slot, 
0， 
offsetof (ngx event conf t, accept mutex) 
NULL }, 
/* 启 用 

















accept mutex 负 载 均衡 锁 后 ， 延 迟 


accept mutex delay 毫 秒 后 再 试图 处 理 新 连接 事件 




















4 
{ ngx string("accept mutex delay"), 
NGX EVENT CONF|NGX CONF TAKE], 
ngx conf set msec slot, 
0, 
offsetof (ngx event conf t, accept mutex delay), 
NULL }, 
// 需要 对 来 自 指定 
IP 的 
TCP 连 接 打印 


debug 级 别 的 调试 日 志 


{ ngx string("debug connection"), 
NGX EVENT CONF|NGX CONF TRAKE1， 
ngx event debug connection, 
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NULL }, 
ngx _ null command 








值得 注意 的 是 ， 上 面 对 于 配置 项 参数 的 解析 使 用 了 在 第 4 章 中 介绍 过 的 Nginx 预 设 的 配置 
项 解析 方法 ， 如 ngx conf set flag slot 和 ngx conf set msec slot。 这 种 自动 解析 配置 项 的 方式 
是 根据 指定 结构 体 中 的 位 置 决定 的 。 下 面 看 一 下 该 模块 定义 的 用 于 存储 配置 项 参数 的 结构 体 


ngx event conf t。 











pedef struct { 
// 连接 池 的 大 小 


ngx uint t connections; 


/* 选 用 的 事件 模块 在 所 有 事件 模块 中 的 序号 ， 也 就 是 





9.4.2 节 中 介绍 过 的 
ctx index 成 员 


*/ 
ngx uint t use; 


// 标志 位 ， 如 果 为 


1， 则 表示 在 接收 到 一 个 新 连接 事件 时 ， 一 次 性 建立 尽 可 能 多 的 连接 


ngx flag t multi accept; 
// 标志 位 ， 为 


1 时 表示 启用 负载 均衡 锁 


ngx flag t accept mutex; 


/* 负 载 均衡 锁 会 使 有 些 
worker 进 程 在 拿 不 到 锁 时 延迟 建立 新 连接 ， 
accept mutex_delay 就 是 这 段 延迟 时 间 的 长 度 。 关 于 它 如 何 影 响 负 和 载 均衡 的 内 容 ， 可 参见 
9.8.5 节 


过 
ngx msec t accept mutex delay; 


// 所 选用 事件 模块 的 名 字 ， 它 与 


use 成 员 是 匹配 的 
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u char *name; 
#if (NGX DEBUG) 
/* 在 一 





with-debug 编 译 模 式 下 ， 可 以 仅 针对 某 些 客户 端 建立 的 连接 输出 调试 级 别 的 日 志 ， 而 


qdqebug_connection 数 组 用 于 保存 这 些 客户 端的 地 址 信息 


4d 

ngx array t debug connection; 
#endif 
} ngx ‘event conf t» 





ngx_event_conf t 结 构 体 中 有 两 个 成 员 与 负载 均衡 锁 相 关 ， 读 者 可 以 在 9.8 节 中 了 解 负载 均 
衡 锁 的 原理 。 


对 于 每 个 事件 模块 都 需要 实现 的 ngx event module t 接 口 ，ngx event core module 模 块 则 
仅 实 现 了 create_conf 方 法 和 init_conf 方 法 ， 这 是 因为 它 并 不 真正 负责 TCP 网 络 事件 的 驱动 ， 所 
以 不 会 实现 ngx event actions t 中 的 方法 ， 如 下 所 示 。 








static ngx str 七 vent core name = ngx string("event core"); 

ngx event module t ngx event core module ctx = { 
&event core name, 
ngx event create conf, /* create configuration 
ngx event init conf, init configuration */ 
{ NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL } 




















最 后 看 一 下 ngx event core module 模 块 的 定义 。 























ngx module t ngx event core module = { 
NGX MODULE V1, 
&ngx event core module ctx, /* module context 
ngx event core commands, module directives 
NGX EVENT MODULE, module type 
NULL, init master 
ngx event module init, init module 
ngx event process init, init process 
NULL, init thread 
NULL, exit thread 
NULL, exit process 
NULL, exit master */ 





NGX MODULE V1 PADDING 





它 实 现 了 ngx event module init 方 法 和 ngx event process init 方 法 。 在 Nginx 启 动 过 程 中 还 
没有 fork 出 worker 子 进程 时 ， 会 首先 调用 ngx event core module 模 块 的 ngx event module init 
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方法 (参见 图 8-6) ， 而 在 fork 出 worker 子 进程 后 ， 每 一 个 worker 进 程 会 在 调用 
ngx event core _ module 模块 的 ngx_event process_init 方 法 后 才 会 进入 正式 的 工作 循环 。 弄 清楚 
这 两 个 方法 何 时 调用 后 ， 下 面 来 看 一 下 它们 究竟 做 了 什么 。 





ngx_event module_init 方 法 其 实 很 简单 ， 它 主要 初始 化 了 一 些 变量 ， 尤 其 是 
ngx_http_stub_status_module 统 计 模 块 使 用 的 一 些 原子 性 的 统计 变量 ， 这 里 不 再 详 述 。 


而 ngx_event_process_init 方 法 就 做 了 许多 事情 ， 下 面 开 始 详细 介绍 它 的 流程 。 


ngx_event_core_module 模 块 在 启动 过 程 中 的 主要 工作 都 是 在 ngx_event process_init 方 法 中 
进行 的 ， 如 图 9-4 所 示 。 


下 面 对 以 上 13 个 步骤 进行 简要 说 明 。 


1) 当 打开 accept mutex 负 载 均 衡 锁 ， 同 时 使 用 了 master 模 式 并 且 worker 进 程 数 量 大 于 1 
时 ， 才 正式 确定 了 进程 将 使 用 accept_ mutex 负 载 均 衡 锁 。 因 此 ， 即 使 我 们 在 配置 文件 中 指定 
打开 accept_mutex 锁 ， 如 果 没 有 使 用 master 模 式 或 者 worker 进 程 数量 等 于 1， 进 程 在 运行 时 还 
是 不 会 使 用 负载 均衡 锁 〈 既 然 不 存在 多 个 进程 去 抢 一 个 监听 端口 上 的 连接 的 情况 ， 那 么 自然 
不 需要 均衡 多 个 worker 进 程 的 负载 ) 。 





这 时 会 将 ngx_use_accept_ mutex 全 局 变量 置 为 1，ngx_accept_ mutex_held 标 志 设 为 0， 
ngx_accept_ mutex_delay 则 设 为 在 配置 文件 中 指定 的 最 大 延迟 时 间 。 这 3 个 变量 的 意义 可 参见 
9.8 节 中 关于 负载 均衡 锁 的 说 明 。 








2) 如 果 没 有 满足 第 1 步 中 的 3 个 条 件 ， 那 么 会 把 ngx_ use_accept mutex 置 为 0， 也 就 是 关闭 
负载 均衡 锁 。 


3) 初始 化 红 黑 树 实现 的 定时 器 。 关 于 定时 右 的 实现 细 市 可 参见 9.6 市 。 


4) 在 调用 use 配 置 项 指定 的 事件 模块 中 ， 在 ngx event module t 接 口 下 ， 
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ngx_event_actions_t 中 的 init 方 法 进行 这 个 事件 模块 的 初始 化 工作 。 
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as em 配置 ，master 模 式 下 worker 进程 数量 大 于 ! ] 





2) 关闭 ngx_use_accept_mutex 锁 1 ) 打 开 ngx_use accept_mutex 锁 


3) 初始 化 红 黑 树 实现 的 
ngx_event_timer_rbtree 定 时 吉 


4) 调用 use 配 置 项 指定 的 事件 驱动 模块 的 
init 方法 









[使 用 timer resolution 设 置 了 时 间 精 度 ] 





5 ) 指定 timer_resolution 坚 秒 后 调用 
ngx_timer_signal_handler 方 法 





[使 用 POLL 事 件 驱 动 ] 


6) 回 cycle 僵 files 数组 预 分 配 运行 时 
使 用 的 连接 句柄 


7) 预 分 配 cycle 之 connections 
数组 充当 连接 池 












8) 预 分 配 所 有 读 事 { 到 


cycle 一 read_events 










9) 预 分 配 所 有 写 


cycle 之 write_events 


10) 将 上 述 le 读 / 写 事件 放 惫 到 


connections 过 


11) 将 connetions orci mie 


cycle >free_connections 指 所 


12) 设置 监听 端口 上 读 事件 的 人 处理 方法 为 


ngx_event _ accept 





13) 将 监听 连接 的 读 事件 添加 
到 事件 驱动 模块 
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图 9-4 ngx_event_core_module 事 件 模 块 启动 时 的 工作 流程 





5) 如 果 nginx.conf 配 置 文件 中 设置 了 timer resolution 配 置 项 ， 即 表明 需要 控制 时 间 精 度 ， 
这 时 会 调用 setitimer 方 法 ， 设 置 时 间 间 隔 为 tmer _ resolution 时 秒 来 回调 ngx timer signal handler 
方法 。 下 面 简单 地 介绍 一 下 Nginx 是 如 何 控制 时 间 精 度 的 。 


ngx_timer_signal handler 方 法 又 做 了 些 什么 呢 ? 其 实 非常 简单 ， 如 下 所 示 。 





void ngx timer signal handler(int signo) 


{ 





ngx event timer alarm = 1; 


} 








ngx_event timer_alarm 只 是 个 全 局 变量 ， 当 它 设 为 时， 表示 需要 更 新 时 间 。 





在 ngx event actions t 的 process_events 方 法 中 ， 每 一 个 事件 驱动 模块 都 需要 在 
ngx event timer alarm 为 1 时 调用 ngx time update 方法 (参见 9.7.1 节 ) 更 新 系统 时 间 ， 在 更 新 


系统 结束 后 需要 将 ngx event timer alarm 设 为 0。 





6) 如 果 使 用 了 epoll 事 件 驱 动 模式 ， 那 么 会 为 ngx_cycle tt 结构 体 中 的 flies 成 员 预 分 配 句 
柄 。 本 音 仅 针对 epoll 事 件 驱 动 模式 ， 有 具体 内 容 不 再 详 述 。 


7) 预 分 配 ngx_connection t 数 组 作为 连接 池 ， 同 时 将 ngx _cycle t 结 构 体 中 的 connections 成 
员 指 回 该 数组 。 数 组 的 个 数 为 nginx.conf 配 置 文件 中 connections 或 worker_connections 中 配置 的 
连接 数 。 


8) 预 分 配 ngx_event t 事 件数 组 作为 读 事 件 池 ， 同 时 将 ngx_cycle_t 结 构 体 中 的 read_events 
成 员 指 问 该 数组 。 数 组 的 个 数 为 nginx.conf 瑟 置 文 件 中 connections 或 worker_connections 里 配置 
的 连接 数 。 


9) 预 分 配 ngx_event t 事 件数 组 作为 写 事 件 池 ， 同 时 将 ngx_cycle tt 结构 体 中 的 write_events 


成 员 指 问 该 数组 。 数 组 的 个 数 为 nginx.conf 瑟 置 文件 中 connections 或 worker_connections 里 配置 
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的 连接 数 。 


10) 按照 序号 ， 将 上 述 3 个 数组 相应 的 恋 / 写 事件 设置 到 每 一 个 ngx_connection_t 连 接 对 象 
中 ， 同 时 把 这 些 连 接 以 ngx connection t 中 的 data 成 员 作为 next 指 针 串 联 成 链表 ， 为 下 一 步 设 置 
空闲 连接 链表 做 好 准备 ， 参 见 图 9-1。 








11) 将 ngx_ cycle tt 结构 体 中 的 空 闪 连接 链表 free_ connections 指 向 connections 数 组 的 最 后 1 
个 元 素 ， 也 就 是 第 10 步 所 有 nsgx_connection t 连 接 通 过 data 成 员 组 成 的 单 链表 的 首部 。 








12) 在 刚刚 建立 好 的 连接 池 中 ， 为 所 有 ngx listening t 监 听 对 象 中 的 connection 成 员 分 配 
连接 ， 同 时 对 监听 端口 的 读 事 件 设置 处 理 方 法 为 ngx_event accept， 也 就 是 说 ， 有 新 连接 事件 
时 将 调用 ngx event accept 方法 建立 新 连接 〈 详 见 9.8 节 中 关于 如 何 建立 新 连接 的 内 容 ) 。 


13) 将 监听 对 象 连接 的 读 事 件 添 加 到 事件 驱动 模块 中 ， 这 样 ，epoll 等 事件 模块 就 开始 检 
测 监听 服务 ， 并 开始 向 用 户 提供 服务 了 。 注 意 ， 打 开 accept_mutex 锁 后 则 不 执行 这 一 步 。 





至 此 ，ngx_event_core_module 模 块 的 启动 工作 就 全 部 结束 了。 下 面 将 以 epoll 事 件 方式 为 
例 来 介绍 实际 的 事件 驱动 模块 是 如 何 处 理事 件 的 。 
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9.6 ”epoll 事 件 驱 动 模块 











本 章 9.1 节 ~9.5 节 都 在 探讨 Nginx 是 如 何 设计 事件 驱动 框架 、 如 何 管理 不 同 的 事件 驱动 模 
块 的 ， 但 本 节 中 将 以 epoll 为 例 ， 讨 论 Linux 操 作 系 统 内 核 是 如 何 实现 epoll 事 件 驱 动机 制 的 ， 
在 简单 了 解 它 的 用 法 后 ， 会 进一步 说 明 ngx epoll module 模 块 是 如 何 基于 epoll 实 现 Nginx 的 事 
件 驱 动 的 。 这 样 读者 就 会 对 Nginx 完 整 的 事件 驱动 设计 方法 有 全 面 的 了 解 ， 同 时 可 以 弄 清 楚 
Nginx 在 几 十 万 并 发 连接 下 是 如 何 做 到 高 效 利 用 服务 器 资源 的 。 


9.6.1 epoll 的 原理 和 用 法 








设想 一 个 场景 : 有 100 万 用 户 同时 与 一 个 进程 保持 着 TCP 连 接 ， 而 每 一 时 刻 只 有 几 十 个 
或 几 百 个 TCP 连 接 是 活跃 的 (接收 到 TCP 包 ) ， 也 就 是 说 ， 在 每 一 时 刻 ， 进 程 只 需要 处 理 这 
100 万 连接 中 的 一 小 部 分 连接 。 那 么 ， 如 何 才 能 高 效 地 处 理 这 种 场景 呢 ? 进程 是 否 在 每 次 询 
问 操作 系统 收集 有 事件 发 生 的 TCP 连 接 时 ， 把 这 100 万 个 连接 告诉 操作 系统 ， 然 后 由 操作 系 
统 找 出 其 中 有 事件 及 生 的 几 百 个 连接 呢 ? 实际 上 ， 在 Linux 内 核 2.4 版 本 以 前 ， 那 时 的 selec 人 或 
者 poll 事 件 驱 动 方式 束 是 这 样 做 的 。 








这 里 有 个 非常 明显 的 问题 ， 即 在 某 一 时 刻 ， 进 程 收集 有 事件 的 连接 时 ， 其 实 这 100 万 连 
接 中 的 大 部 分 都 是 没有 事件 发 生 的 。 因 此 ， 如 果 每 次 收集 事件 时 ， 都 把 这 100 万 连接 的 套 接 
字 传 给 操作 系统 〈 这 首先 就 是 用 户 态 内 存 到 内 核 态 内 存 的 大 量 复制 ) ， 而 由 操作 系统 内 核 寻 
找 这 些 连接 上 有 没有 未 处 理 的 事件 ， 将 会 是 巨大 的 资源 浪费 ， 然 而 select 和 poll 就 是 这 样 做 
的 ， 因 此 它们 最 多 只 能 处 理 几 千 个 并 发 连接 。 而 epoll 不 这 样 做 ， 它 在 Linux 内 核 中 申请 了 一 
个 简易 的 文件 系统 ， 把 原先 的 一 个 select 或 者 poll 调 用 分 成 了 3 个 部 分 :调用 epoll_create 建 并 1 
个 epoll 对 象 〈 在 epoll 文 件 系统 中 给 这 个 句柄 分 配 资源 ) 、 调 用 epoll _cd 回 epoll 对 象 中 添加 这 
100 万 个 连接 的 套 接 字 、 调 用 epoll_wait 收 集 发 生 事件 的 连接 。 这 样 ， 只 需要 在 进程 启动 时 建 


A 者 二 开导 各 定 中 拓 可、 因此 在 引 人 
































时 ，epoll_wait 的 效率 就 会 非常 高 ， 因 为 调用 epoll wait 时 并 没有 向 它 传 递 这 100 万 个 连接 ， 内 
核 也 不 需要 去 遍历 全 部 的 连接 。 


那么 ，Linux 内 核 将 如 何 实现 以 上 的 想法 呢 ? 下 面 以 Linux 内 核 2.6.3$ 版 本 为 例 ， 简 单 说 明 
一 下 epoll 是 如 何 高 效 处 理事 件 的 。 图 9-5 展 示 了 epoll 的 内 部 主要 数据 结构 是 如 何 安排 的 。 





当 某 一 个 进程 调用 epoll_create 方 法 时 ，Linux 内 核 会 创建 一 个 eventpoll 结 构 体 ， 这 个 结构 
体 中 有 两 个 成 员 与 epoll 的 使 用 方式 密切 相关 ， 如 下 所 示 。 





struct eventpoll { 


/* 红 黑 树 的 根 节 点 ， 这 棵 树 中 存储 着 所 有 添加 到 


epoll 中 的 事件 ， 也 就 是 这 个 





epoll 监 挖 的 事件 


struct rb root rbr; 


// 双向 链表 


rdl1list 保 存 着 将 要 通过 


TiNNNNNinNnnn http://wWwWw linuxorobe.con 





epoll wait 返 回 给 用 户 的 、 满 足 条 件 的 事件 


struct list head rdllist; 


eventpoll 









红 黑 树 中 每 个 节点 都 
是 基于 epitem 结 构 中 
的 rdllink 成 员 






红 黑 树 中 
每 个 节点 


都 是 AE: 基于 
epitem 中 
忌 中 的 
() rhn 成 员 


图 9-5 epoll 原 理 示意 图 


每 一 个 epol 对 象 都 有 一 个 独立 的 eventpoll 结 构 体 ， 这 个 结构 体会 在 内 核 空 间 中 创造 独立 


的 内 存 和 证 I | 月 pepol EE an 的 i er dbe 人 





黑 树 中 ， 这 样 ， 重 复 添加 的 事件 就 可 以 通过 红 黑 树 而 高 效 地 识别 出 来 (epoll_ctl 方 法 会 很 
快 )。Linux 内 核 中 的 这 标 红 黑 树 与 第 7 章 中 介绍 的 Nginx 红 黑 树 是 非常 相似 的 ， 可 以 参照 
ngx_rbtree t 容 器 进行 理解 。 





所 有 添加 到 epoll 中 的 事件 都 会 与 设备 〈 如 网 卡 ) 驱动 程序 建立 回调 关系 ， 也 就 是 说 ， 相 
应 的 事件 发 生 时 会 调用 这 里 的 回调 方法 。 这 个 回调 方法 在 内 核 中 叫做 ep_poll_callback， 它 会 
把 这 样 的 事件 放 到 上 面 的 rdllist 双 回 链 表 中 。 这 个 内 核 中 的 双 辐 链表 与 ngx _ queue t 容 句 几 乎 
是 完全 相同 的 (Nginx 代 码 与 Linux 内 核 代码 很 相似 〉，， 我 们 可 以 参照 着 理解 。 在 epoll 中 ， 对 
于 每 一 个 事件 都 会 建立 一 个 epitem 结 构 体 ， 如 下 所 示 。 





struct epitem { 


// 红 黑 树 节点 ， 与 第 


7 章 中 的 


ngx_ rbtree node 七 红 黑 树 节点 相似 


struct rb node rbn; 


// 双向 链表 节点 ， 与 第 


7 章 中 的 


口 岂 所 岂 有 有 和 所 掉 由 http' /wNv inuxorobe. con 





ngx_queue 七 双向 链表 节点 相似 


struct list head rdllink; 


// 事件 句柄 等 信息 


struct epoll filefd ffd; 


// 指向 其 所 属 的 


eventpoll 对 和 象 


struct eventpoll *ep; 





// 期 待 的 事件 类 型 





struct epoll event event; 








这 里 包含 每 一 个 事件 对 应 着 的 信息 。 
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当 调 用 epoll_wait 检 查 是 否 有 发 生 事件 的 连接 时 ， 只 是 检查 eventpoll 对 象 中 的 rdllist 双 问 
链表 是 否 有 epitem 元 素 而 已 ， 如 果 rdllis 链 表 不 为 空 ， 则 把 这 里 的 事件 复制 到 用 户 态 内 存 中 ， 
同时 将 事件 数量 返回 给 用 户 。 因 此 ，epoll_wait 的 效率 非常 高 。epoll_ctl 在 向 epoll 对 象 中 添 
加 、 修 改 、 删 除 事件 时 ， 从 rbr 红 黑 树 中 查找 事件 也 非常 快 ， 也 就 是 说 ，epoll 是 非常 高 效 
的 ， 它 可 以 轻易 地 处 理 百 万 级 别 的 并 发 连接 。 


9.6.2 ”如 何 使 用 epoll 


epoll 通 过 下 面 3 个 epoll 系 统 调用 为 用 户 提 供 服 务 。 
(1) epoll_create 系 统 调用 


epoll_create 在 C 库 中 的 原型 如 下 。 





int epoll create(int size); 





epoll_create 返 回 一 个 句柄 ， 之 后 epoll 的 使 用 都 将 依靠 这 个 句柄 来 标识 。 参 数 size 是 告诉 
epoll 所 要 处 理 的 大 致 事件 数目 。 不 再 使 用 epoll 时 ， 必 须 调 用 close 关 闭 这 个 句柄 。 


© 注意 size 参数 只 是 告诉 内 核 这 个 epoll 对 象 会 处 理 的 事件 大 臻 数目， 而 不 是 能 够 处 理 
的 事件 的 最 大 个 数 。 在 Linux 最 新 的 一 些 内 核 版 本 的 实现 中 ， 这 个 size 参 数 没 有 任何 意义 。 


(2) epoll ct 系统 调用 


epoll_ctl 在 C 库 中 的 原型 如 下 。 





int epoll ctll(int epfd,int op,int fd,struct epoll event* event); 








epoll_ct 回 epol 对 象 中 添加 、 修 改 或 者 删除 感 兴趣 的 事件 ， 返 回 0 表 示 成 功 ， 人 否则 返回 - 
1， 此 时 需要 根据 errno 错 误 码 判断 错误 类 型 。epoll wait 方 法 返回 的 事件 必然 是 通过 epoll_ctl 
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添加 到 epoll 中 的 。 参 数 epfd 是 epoll_create 返 


op 


EPOLL 
EPOLL 


EPOLL 


表 9-2 epoll_ctl 系 统 调用 中 第 2 个 参数 的 取 值 意义 


反 回 的 句柄 ， 而 op 参数 的 意义 见 表 9-2。 


的 取 值 意 义 

GIL :ADD 添加 新 的 事件 到 epoll 中 

CTL MOD 修改 epoll 中 的 事件 
TE DEL 删除 epoll 中 的 事件 


第 3 个 参数 妇 是 待 监测 的 连接 套 接 字 ， 第 4 个 参数 是 在 告诉 epol 对 什么 样 的 事件 感 兴 


它 使 用 了 epoll_event 


构 体 ， 而 在 epitem 中 有 一 





struct epoll event{ 





吉 构 体 ， 在 上 文 介绍 过 的 epoll 实 现 机 制 中 会 为 每 一 个 事件 创建 epitem2 
个 epoll event 类 型 的 event 成 员 。 下 面 看 一 下 epoll event 的 定义 。 


_ uint32 t events; 


epoll data t data; 





events 的 取 值 见 表 9-3。 


events 取 值 


EPOLLIN 


EPOLLOUT 建 、 
EPOLLRDHUP 
EPOLLPRI 
EPOLLERR 
EPOLLHUP 
EPOLLET 
EPOLLONESHOT _ 


表 9-3 ”epoll_event 中 events 的 取 值 意义 


表示 对 应 的 连接 上 有 数据 可 以 读 出 (TCP 连接 的 远 端 主动 关闭 连接 ， 
为 需要 处 理发 送 来 的 FIN 包 ) 


表示 对 应 的 连接 上 可 以 写 入 数据 发 送 (主动 向 上 游 服 务 器 发 起 非 阻塞 的 TCP 连接 ， 


立成 功 的 事件 相当 于 可 写 事 件 ) 


表示 TCP 连接 的 远 端 关闭 或 半 关 闭 连接 
表示 对 应 的 连接 上 有 紧急 数据 需要 读 
表示 对 应 的 连接 发 生 误 

表示 对 应 的 连接 被 挂 起 


表示 将 触发 方式 设置 为 边缘 触发 (ET)， 系 统 默 认为 水 平 触发 (LT) 


_ 表 示 对 这 个 事件 只 处 理 一 次 ,, 下 次 需要 处 理 时 需 重 新 加 入 epoll 


也 相当 于 可 读 事件 ， 
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连接 


而 data 成 员 是 一 个 epoll _ data 联合， 其 定义 如 下 。 





typedef union epoll data { 


void *ptr; 
int fd 

uint32 七 Ne， 
uint64 t u64; 


} epoll data t; 





可 见 ， 这 个 data 成 员 还 与 具体 的 使 用 方式 相关 。 例 如 ，ngx epoll module 模 块 只 使 用 了 联 
合 中 的 ptr 成 员 ， 作 为 指 同 ngx_connection t 连 接 的 指针 。 


(3) epoll wait 系 统 调 用 


epoll_wait 在 C 库 中 的 原型 如 下 。 





int epoll wait (int epfd,struct epoll event* events,int maxevents,int timeout); 








收集 在 epoll 监控 的 事件 中 已 经 发 生 的 事件 ， 如 果 epol 中 没有 任何 一 个 事件 发 生 ， 则 最 多 
等 待 fmeout 毫 秒 后 返回 。epoll_wait 的 返回 值 表 示 当 前 发 生 的 事件 个 数 ， 如 果 返 回 0， 则 表示 
本 次 调用 中 没有 事件 发 生 ， 如 果 人 返回 -1， 则 表示 出 现 错误 ， 需 要 检查 errno 错 误 人 码 判 断 错误 类 
型 。 第 1 个 参数 epfd 是 epoll 的 描述 符 。 第 2 个 参数 events 则 是 分 配 好 的 epoll_event 结 构 体 数 组 ， 
epoll 将 会 把 发 生 的 事件 复制 到 events 数 组 中 (events 不 可 以 是 空 指 针 ， 内 核 只 负责 把 数据 复制 
到 这 个 events 数 组 中 ， 不 会 去 帮助 我 们 在 用 户 态 中 分 配 内 存 。 内 核 这 种 做 法 效率 很 局 ) 。 第 3 
个 参数 maxevents 表 示 本 次 可 以 返回 的 最 大 事件 数目 ， 通 常 maxevents 参 数 与 预 分 配 的 events 数 
组 的 大 小 是 相等 的 。 第 4 个 参数 timeout 表 示 在 没有 检测 到 事件 发 生 时 最 多 等 待 的 时 间 〈 单 位 
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为 毫秒 ) ， 如 果 timeout 为 0， 则 表示 epoll_wait 在 rdllist 链 表 中 为 空 ， 立 刻 返 回 ， 不 会 等 待 。 


epoll 有 两 种 工作 模式 : IT 《水平 触发 ) 模式 和 ET (边缘 触发 ) 模式 。 默 认 情 况 下 ， 
epoll 和 采用 IT 模式 工作 ， 这 时 可 以 处 理 阻 塞 和 非 阻塞 套 接 字 ， 而 表 9-3 中 的 EPOLLET 表 示 可 以 
将 一 个 事件 改 为 ET 模式 。ET 模 式 的 效率 要 比 IT 模 式 高 ， 它 只 支持 非 阻 塞 套 接 字 。ET 模 式 与 
IT 模式 的 区 别 在 于 ， 当 一 个 新 的 事件 到 来 时 ，ET 模 式 下 当然 可 以 从 epoll wait 调用 中 获取 到 
这 个 事件 ， 可 是 如 果 这 次 没有 把 这 个 事件 对 应 的 套 接 字 缓 冲 区 处理 完 ， 在 这 个 套 接 字 没有 新 
的 事件 再 次 到 来 时 ， 在 ET 模式 下 是 无 法 再 次 从 epoll_wait 调 用 中 获取 这 个 事件 的 ， 而 LT 模式 
则 相反 ， 只 要 一 个 事件 对 应 的 套 接 字 缓 冲 区 还 有 数据 ， 就 总 能 从 epoll_wait 中 获取 这 个 事 
件 。 因 此 ， 在 LT 模式 下 开发 基于 epoll 的 应 用 要 简单 一 些 ， 不 太 容 易 出 错 ， 而 在 ET 模式 下 事 
件 发 生 时 ， 如 果 没 有 彻底 地 将 缓冲 区 数据 处 理 完 ， 则 会 导致 缓冲 区 中 的 用 户 请 求 得 不 到 响 
应 。 默 认 情况 下 ，Nginx 是 通过 ET 模式 使 用 epoll 的 ， 在 下 文中 就 可 以 看 到 相关 内 容 。 














9.6.3 ngx epoll module 模 块 的 实现 


本 节 主 要 介绍 事件 驱动 模块 接口 与 epoll 用 法 是 如 何 结合 起 来 发 挥 作用 的 。 首 先 看 一 下 
ngx_epoll_ module 模块 究竟 对 哪些 配置 项 感 兴趣 ， 其 中 ngx_epoll _ commands 数 组 指明 了 影响 其 
可 定制 性 的 两 个 配置 项 。 





static ngx command t ngx epoll commands [] = { 





/* 在 调用 


epoll wait 时 ， 将 由 第 
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3 个 参数 告诉 


Linux 内 核 一 次 最 多 可 返回 多 少 个 事件 。 这 个 配置 项 表示 调用 一 次 





epoll _ wait 时 最 多 可 以 返回 的 事件 数 ， 当 然 ， 它 也 会 预 分 配 那么 多 


epoll_event 结 构 体 用 于 存储 事件 


G4 


{ ngx string("epoll events"), 

















NGX EVENT CONF|NGX CONF TAKE1， 


ngx conf set num slot, 





offsetof (ngx epoll conf t, events), 
NULL }, 


/* 指 明 在 开启 异步 


I/O 且 使 用 


io_setup 系 统 调用 初始 化 异步 
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I/O 上 下 文 环 境 时 


， 初始 分 配 的 异步 


I/O 事 件 个 数 ， 详 见 


*/ 


{ ngx string ("worker aio requests"), 

















NGX EVENT CONF|NGX CONF TAKE], 


ngx conf set num slot, 





offsetof (ngx epoll conf t, aio requests), NULL }, 





ngx null command 








上 面 使 用 了 预 分 配 的 ngx conf set num slot 方 法 来 解析 这 两 个 配置 项 ， 下 面 看 一 下 存储 
配置 项 的 结构 体 ngx epoll conf t。 





ngx epoll conf 七 。 
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ngx uint t events; 


ngx uint t aio requests; 


} ngx epoll conf t; 





其 中 ，events 是 调用 epoll_wait 方 法 时 传 入 的 第 3 个 参数 maxevents， 而 第 2 个 参数 events 数 
组 的 大 小 也 是 由 它 决定 的 ， 下 面 将 在 ngx epoll init 方 法 中 初始 化 这 个 数组 。 


接 下 来 看 一 下 epoll 是 如 何 定 义 ngx event module t 事 件 模 块 接口 的 ， 代 码 如 下 。 





static ngx str t epoll name = ngx string("epoll"); ngx event module t ngx epoll module ctx = { 





&epoll name, 


ngx epoll create conf, 





ngx epoll init conf, 


// 对 应 于 


ngx event actions 七 中 的 


add 方 法 


ngx epoll add event, 


// 对 应 于 
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ngx_event_actions 七 中 的 


del 方 法 


ngx epoll del event, 


// 对 应 于 


ngx event actions 七 中 的 


enable 方 法 ， 与 


add 方 法 一 致 


ngx epoll add event, 


// 对 应 于 


ngx event actions 七 中 的 


disable 方法 ， 与 
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de1 方 法 一 致 


ngx epoll del event, 


// 对 应 于 


ngx event actions 七 中 的 


adqd conn 方 法 


ngx epoll add connection, 


// 对 应 于 


ngx event actions 七 中 的 


del conn 方 法 


ngx epoll del connection, 





// 未 实现 
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ngx event actions 七 中 的 


Process_changes 方 法 


NULL, 


// 对 应 于 


ngx event actions 七 中 的 


process _ events 方 法 


ngx epoll process events, 


// 对 应 于 


ngx event actions 七 中 的 


init 方 法 


ngx epoll init, 


// 对 应 于 


NNnNn httpo://ww linuxorobe. con 





ngx event actions 七 中 的 


done 方 法 


ngx epoll done, 





其 中 ，ngx epoll create conf 方 法 和 ngx epoll init conf 方 法 只 是 为 了 解析 配置 项 ， 略 过 不 
提 ， 下 面 重 点 看 一 下 ngx_event actions t 中 的 10 个 接口 是 如 何 实现 的 。 


首先 从 实现 init 接 口 的 ngx epoll init 方 法 讲 起 。ngx epoll-init 方 法 是 在 什么 时 候 被 调用 的 
呢 ? 在 图 9-4 的 第 4 步 中 它 会 被 调用 ， 也 就 是 Nginx 的 启动 过 程 中 。ngx epoll init 方 法 主要 做 了 
两 件 事 : 


1) 调用 epoll create 方 法 创建 epoll 对 象 。 
2) 创建 event list 数 组 ， 用 于 进行 epoll_wait 调 用 时 传递 内 核 态 的 事件 。 


event list 数 组 就 是 用 于 在 epoll _ wait 调用 中 接收 事件 的 参数 ， 如 下 所 示 。 





static int ep = -1; 





static struct epoll event *event list; 


static ngx uint t nevents; 








其 中 ，ep 是 epoll 对 象 的 描述 符 ，nevents 是 上 面 说 到 的 epoll_events 配 置 项 参数 ， 它 既 指明 
了 epoll _ wait 一 次 返回 的 最 大 事件 数 ， 也 告诉 了 event_ list 应 该 分 配 的 数组 大 小 。ngx_epoll init 
方法 代码 如 下 所 示 。 





static ngx int t ngx epoll init (ngx Cycle t *cycle, ngx msec 七 timer) { 





ngx epoll conf 七 *epcf; 


/* 获 取 


create conf 中 生成 的 


ngx epoll conf 结构 体 ， 它 已 经 被 赋予 解析 完 配 置 文件 后 的 值 。 详 细 内 容 可 参见 


9.4.1 节 中 关于 


ngx event get conf 宏 的 用 法 


2 





pcf = ngx event get conf(cycle->conf ctx, ngx epoll module); if (ep == -1) { 


/* 调 用 


epoll create 在 内 核 中 创建 


epoll 对 象 。 上 文 已 经 讲 过 ， 参 数 
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size 不 是 用 于 指明 


epoll 能 够 处 理 的 最 大 事件 个 数 ， 因 为 在 许多 





Linux 内 核 版 本 中 ， 


epol1 是 不 处 理 这 个 参数 的 ， 所 以 设 为 


cycle-> connection n/2 (而 不 是 


cycle->connection n) 也 不 要 紧 


人 


ep = epoll create(cycle->connection n/2); if (ep == -1) 





ngx_ log error (NGX LOG F 








M 





ERG, Cycle->log, ngx errno, 

















#if (NGX HAVE FILE AIO) 


// 异步 


I/O 内 容 可 参见 


{ 


"epoll create () 


failed"); return NGX 





ERROR; 
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ngx epoll aio init(cycle, epcf); 


#endif 


if (nevents < epcf->events) { 





if (event list) { 


ngx freel(levent list); 


// 初始 化 


event 1ist 数 组 。 数 组 的 个 数 是 配置 项 


epoll events 的 参数 


event list = ngx alloc(sizeof (struct epoll event) 


return NGX ERROR; 





nevents 也 是 配置 


大 





pcf->events, cycle->1log); if (event list == NULL) 
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epoll events 的 参数 





nevents = epcf->events; 


// 指明 读 写 


I/O 的 方法 ， 本 章 不 做 具体 说 明 


ngx_ io = ngx os io， 


// 设置 


ngx_event_actions 接 口 





ngx event _ actions = ngx epoll module ctx.actions; #if (NGX HAVE CLEAR EVENT) 




















/* 默 认 是 采用 


ET 模式 来 使 用 





epoll 的 ， 
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NGX_USE CLEAR EVENT 宏 实际 上 就 是 在 告诉 














Nginx 使 用 


ET 模式 





类 








ngx event flags = NGX USE CLEAR EVENT 














#else 








| 
四 
= 





EVENT 





ngx event flags = NGX USE L 











#endif 





|INGX USE GREEDY EVENT 























INGX USE EPOLL EVENT; return NGX OR; 




















ngx_event_actions 是 在 Nginx 事 件 框架 处 理事 件 时 封装 的 接口 ， 我 们 会 在 9.8 节 中 说 明 它 的 
用 法 。 


对 于 epoll 而 言 ， 并 没有 enable 事 件 和 disable 事 件 的 概念 ， 另 外 ， 从 ngx_epoll module_ctx 
结构 体 中 可 以 看 出 ，enable 和 add 接 口 都 是 使 用 ngx epoll add event 方 法 实现 的 ， 而 disable 和 
del 接 口 都 是 使 用 ngx_epoll_del_event 方 法 实现 的 。 下 面 以 ngx_epoll add_event 方 法 为 例 介绍 一 
下 它们 是 如 何 调用 epoll_ctl 向 epoll 中 添加 事件 或 从 epoll 中 删除 事件 的 。 





static ngx int t 
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ngx epoll adq event (ngx event 七 *ev ngx int t event, ngx uint t flags) { 


int OP7 

uint32 t events, prev; 
ngx event 七 ye 

ngx connection 七 *Oy 


struct epoll event ; 








// 每 个 事件 的 


data 成 员 都 存放 着 其 对 应 的 


ngx connection 七 连 接 


C = ev->data; 








/* 下 面 会 根据 
event 参 数 确定 当前 事件 是 读 事件 还 是 写 事件 ， 这 会 决定 
events 是 加 上 


EPOLLIN 标 志 位 还 是 
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EPOLLOUT 标 志 位 


*/ 


events = (uint32 t) event; 


// 根据 





active 标 志 位 确定 是 否 为 活跃 事件 ， 以 决定 到 底 是 修改 还 是 添加 事件 


if (e->active) 1{ 





op = EPOLL CTL MOD; 


} else { 


op = EPOLL CTL ADD; 





// 加 入 


i 中 站 站 站 站 门 htt po: // Waw | | NUXPr obe, CON 





events 标 志 位 中 





.events = events | (uint32 t) flags; /*ptr 成 员 存 储 的 是 


ngx_connection tt 上 连接， 可 参见 


epol1 的 使 用 方式 。 在 


9.2 节 中 曾经 提 到 过 事件 的 





instance 标 志 人 位， 下面 就 配合 


ngx epoll process_events 方 法 说 明 它 的 用 法 


ee.data.ptr = (void *) ((uintptr t) c | ev->instance); // 调用 


epoll ctl1 方 法 向 
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epol1 中 添加 事件 或 者 在 


epoll 中 修改 事件 


if (epoll ctl(ep, op, c->fqd, 


ngx log error (NGX LOG AL 





// 将 事件 的 


active 标 志 位 置 为 





1， 表 示 当 前 事件 是 活跃 的 


ev->active = 1; 


return NGX OK; 


&ee) == -1) { 


ERT, ev->log, ngx errno, 


"epoll ctl(%d, %d) 


failed", 


op, Cc->fd); return NGX 


ERR 











ngx epoll del event 方 法 也 通过 epoll_ ctl 删除 epoll 中 的 事件 ， 具 体 代 码 这 里 不 再 罗列 ， 读 


者 可 参照 ngx epoll add event 


的 实现 理解 其 意义 。 


对 于 ngx epoll add connection 方 法 和 ngx epoll del connection 方 法 ， 也 是 调用 epoll ctl 方 
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法 同 epoll 中 添加 事件 或 者 在 epoll 中 删除 事件 的 ， 只 是 每 一 个 连接 都 对 应 读 / 写 事件 。 因 此 ， 
ngx epoll add connection 方 法 和 ngx epoll del connection 方 法 在 每 次 执行 时 也 都 是 同时 将 每 个 
连接 对 应 的 谈 、 写 事件 active 标 志 位 置 为 1 的 ， 这 里 将 不 再 给 出 其 代码 。 


对 于 事件 的 instance 标 志 位 ， 已 经 在 9.2 节 中 简单 地 介绍 了 它 的 意义 ， 下 面 将 结合 
ngx epoll process_events 方 法 具体 说 明 其 意义 。ngx epoll process_events 是 实现 了 收集 、 分 发 
事件 的 process_events 接 口 的 方法 ， 其 主要 代码 如 下 所 示 。 








static ngx int t ngx epoll process events (ngx cycle t *cycle, ngx msec t timer, ngx uint t flags) { 








int events; 

uint32 t revents; 

ngx int t instance, i; 

ngx event t *rev, wev, *queue; ngx connection 七 *oc; 
/* 调 用 


epoll wait 获 取 事 件 。 注 意 ， 


timer 参 数 是 在 


process events 调 用 时 传 入 的 ， 在 


9.7 和 
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9.8 节 中 会 提 到 这 个 参数 





*/ 
events = epoll wait(ep, event list, (int) nevents, timer); … 
/* 在 
9.7 节 中 会 介绍 
Nginx 对 时 间 的 缓存 和 管理 。 当 
flags 标 志 位 指示 要 更 新 时 间 时 ， 就 是 在 这 里 更 新 的 
*/ 
if (flags & NGX UPDATE TIME || ngx event timer alarm) { 











// 更 新 时 间 ， 参 见 


ngx time update(); 
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// 遍历 本 次 


epoll _ wait 返回 的 所 有 事件 


for (i = 0; i < events; i++) { 


/* 对 照 着 上 面 提 到 的 


ngx epoll add event 方 法 ， 可 以 看 到 


ptr 成 员 就 是 


ngx connection 七 连接 的 地 址 ， 但 最 后 


1 位 有 特殊 含义 ， 需 要 把 它 屏 项 掉 
4 
c= event listl[lil data:ptr; 


// 将 地 址 的 最 后 一 位 取出 来 ， 用 


instance 变 量 标识 
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instance = (uintptr t) c & 1; 


/* 无 论 是 


32 位 还 


各 


64 位 机 器 ， 其 地 址 的 最 后 


0， 可 以 用 下 面 这 行 语句 把 


ngx_ connection 七 的 地 址 还 原 到 真正 的 地 址 值 








*/ 
c= (ngx connection t *) ((uintptr t) c & (uintptr t) ~1); // 取出 读 事 件 
rev = c->read; 
// 判断 这 个 读 事件 是 否 为 过 期 事件 
if (c->fd == -1 || rev->instance != instance) { 
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fd 套 接 字 描 述 符 为 


-1 或 者 


instance 标 志 位 不 相等 时 ， 表 示 这 个 事件 已 经 过 期 了 ， 不 用 处 理 


*/ 


continue; 


// 取出 事件 类 型 


revents = event listl[i] .events; 





// 如 果 是 读 事 件 且 该 事件 是 活跃 的 





if ((revents & EPOLLIN) && rev->active) { 
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// flags 参 数 中 含有 














NGX_ POST _ EVENTS 表 示 这 批 事件 要 延 后 处 理 





if (flags & NGX POST EVENTS) { 











/* 如 果 要 在 





post 队 列 中 延 后 处 理 该 事件 ， 首 先 要 判断 它 是 新 连接 事件 还 是 普通 事件 ， 以 决定 把 它 加 入 到 


ngx posted accept events 队 列 或 者 





ngx_posted events 队 列 中 。 关 于 





post 队 列 中 的 事件 何 时 执行 ， 可 参见 


*/ 





queue = (ngx event t **) (rev->accept &ngx posted accept events : &ngx posted events); // 将 这 人 1 





ngx locked post event (rev, queue); } else | 


站 门 介 /全 哇 ss 伯 中 万 竺 二 ^# 中 tt po: / /WA | 1 nuxpr obe. Con 








rev->handler (eV) 


// 取出 写 事 件 


WeV = CcC->write; 





if ((revents & EPOLLOUT) && wev->active) { 





// 判断 这 个 读 事件 是 否 为 过 期 事件 


if (c->fd == -1 || wev->instance != instance) { 


/* 当 


fd 和 套 接 字 描 述 符 为 


-1 或 者 


instance 标 志 位 不 相等 时 ， 表 示 这 个 事件 已 经 过 期 了 ， 不 用 处 理 


B84 
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continue; 














if (flags & NGX POST EVENTS) { 


// 将 这 个 事件 添加 到 


post 队 列 中 延 后 处 理 


ngx locked post event (wev, &ngx posted events); } else { 


// 立即 调用 这 个 写 事件 的 回调 方法 来 处 理 这 个 事件 


wev->handler (weV) 


return NGX OK; 
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ngx_epoll_process_events 方 法 会 收集 当前 触发 的 所 有 事件 ， 对 于 不 需要 加 入 到 post 队 列 延 
后 处 理 的 事件 ， 该 方法 会 立刻 执行 它们 的 回调 方法 ， 这 其 实 是 在 做 分 发 事件 的 工作 ， 只 是 它 
会 在 自己 的 进程 中 调用 这 些 回调 方法 而 已 ， 因 此 ， 每 一 个 回调 方法 都 不 能 导致 进程 休眠 或 者 


消耗 太 多 的 时 间 ， 以 免 epoll 不 能 即时 地 处 理 其 他 事件 。 


instance 标 志 位 为 什么 可 以 判断 事件 是 否 过 期 ? 从 上 面 的 代码 可 以 看 出 ，instance 标 志 位 
的 使 用 其 实 很 简单 ， 它 利用 了 指针 的 最 后 一 位 一 定 是 0 这 一 特性 。 既 然 最 后 一 位 始终 都 是 0， 
那么 不 如 用 来 表示 instance。 这 样 ， 在 使 用 ngx epoll add event 方 法 向 epoll 中 添加 事件 时 ， 就 
把 epoll_event 中 联合 成 员 data 的 ptr 成 员 指 向 ngx_connection t 连 接 的 地 址 ， 同 时 把 最 后 一 位 置 








为 这 个 事件 的 instance 标 志 。 而 在 ngx epoll process_events 方 法 中 取出 指向 连接 的 ptr 地 址 时 ， 
先 把 最 后 一 位 instance 取 出 来 ， 再 把 ptr 还 原 成 正常 的 地 址 赋 给 ngx_connection t 连 接 。 这 样 ， 
instance 究 竟 放 在 何 处 的 问题 也 就 解决 了 。 


那么 ， 过 期 事件 又 是 怎么 回 事 呢 ? 举 个 例子 ， 假 设 epoll_wait 一 次 返回 3 个 事件 ， 在 第 1 
个 事件 的 处 理 过程 中 ， 由 于 业务 的 需要 ， 所 以 关闭 了 一 个 连接 ， 而 这 个 连接 恰好 对 应 第 3 个 
事件 。 这 样 的 话 ， 在 处 理 到 第 3 个 事件 时 ， 这 个 事件 就 已 经 是 过 期 事件 了 ， 一 旦 处 理 必然 出 
错 。 既 然 如 此 ， 把 关闭 的 这 个 连接 的 他 套 接 字 置 为 -1 能 解决 问题 吗 ? 答案 是 不 能 处 理 所 有 情 
况 。 





下 面 先 来 看 看 这 种 貌似 不 可 能 发 生 的 场景 到 底 是 怎么 发 生 的 ， 假 设 第 3 个 事件 对 应 的 
ngx_connection ft 连接 中 的 人 包 套 接 字 原先 是 50， 处 理 第 1 个 事件 时 把 这 个 连接 的 套 接 字 关闭 了 ， 
同时 置 为 -1， 并 且 调 用 ngx free_connection 将 该 连接 归还 给 连接 池 。 在 
ngx epoll process_events 方 法 的 循环 中 开始 处 理 第 2 个 事件 ， 恰 好 第 2 个 事件 是 建立 新 连接 事 
件 ， 调 用 ngx_get_connection 从 连接 池 中 取出 的 连接 非常 可 能 就 是 刚刚 释放 的 第 3 个 事件 对 应 
的 连接 。 由 于 套 接 字 50 刚 刚 被 释放 ，Linux 内 核 非常 有 可 能 把 刚刚 释放 的 套 接 字 50 又 分 配给 
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新 建立 的 连接 。 因 此 ， 在 循环 中 处 理 第 3 个 事件 时 ， 这 个 事件 就 是 过 期 的 了 ! 它 对 应 的 事件 
征 关 闭 的 连接 ， 而 不 是 新 建立 的 连接 。 


如 何 解 决 这 个 问题 ? 依靠 instance 标 志 位 。 当 调用 ngx _get connection 从 连接 池 中 获取 一 个 
新 连接 时 ，instance 标 志 位 束 会 置 反 ， 代 码 如 下 所 示 。 





ngx connection 七 * 


ngx get connection(ngx _ Socket t s, ngx log t *log) { 


// 从 连接 池 中 获取 一 个 连接 


ngx Connection 七 *c;} 


C = ngx cycle->free connections; 


rev = Cc->read; 


WeV = CcC->write; 


instance = rev->instance; 
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// 将 


instance 标 志 位 置 为 原来 的 相反 值 


rev->instance = !instance; 


wev->instance = !instance; 


return c; 





这 样 ， 当 这 个 ngx_connection t 连 接 重复 使 用 时 ， 它 的 instance 标 志 位 一 定 是 不 同 的 。 因 
此 ， 在 ngx epoll_ process events 方 法 中 一 旦 判断 instance 发 生 了 变化 ， 就 认为 这 是 过 期 事件 而 
不 予 处 理 。 这 种 设计 方法 是 非常 值得 读者 学 习 的 ， 因 为 它 几乎 没有 增加 任何 成 本 就 很 好 地 和 解 
决 了 服务 器 开发 时 一 定 会 出 现 的 过 期 事件 问题 。 











目前 ， 在 ngx_event actions t 接 口中 ， 所 有 事件 模块 都 没有 实现 process_changes 方 法 。 
done 接 口 是 由 ngx epoll done 方 法 实现 的 ， 在 Nginx 退 出 服务 时 它 会 得 到 调用 。ngx epoll done 
主要 是 关闭 epoll 描 述 符 ep， 同 时 释放 event list 数 组 。 


了 解 了 ngx_epoll_module_ctx 中 所 有 接口 的 实现 后 ，ngx_epoll_module 模 块 的 定义 就 非常 
简单 了 ， 如 下 所 示 。 





ngx module t ngx epoll module = { 
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NGX MODULE V1, 





&ngx epoll module ctx, 





ngx epoll commands, 

















NGX_ EVENT MODULE, 


NULL, 











NULL, 





NULL, 


NULL, 


NULL, 


NULL, 


NULL, 


NGX MODULE V1 PADDING 





/* module context */ 


/* module directives */ 





/* module type */ 


/* 


/* 


/* 


/* 


init master */ 


init module */ 


init process */ 


init thread */ 


exit thread */ 


exit process */ 


exit master */ 








这 里 不 需要 再 实现 ngx module t 接 口中 的 7 个 回调 方法 了 。 





至 此 ， 我 们 完整 地 介绍 了 ngx epoll module 模 块 是 如 何 实现 事件 驱动 机 制 的 内 容 的 。 事 
实 上 ， 其 他 事件 驱动 模块 的 实现 与 ngx epoll module 模 块 的 差别 并 不 是 很 大 ， 读 者 可 以 参照 


本 节 内 容 阅 读 其 他 事件 模块 的 源 代码 。 
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9.7 ”定时 器 事件 








Nginx 实 现 了 自己 的 定时 器 触发 机 制 ， 它 与 epoll 等 事件 驱动 模块 处 理 的 网 络 事件 不 同 : 
在 网 络 事件 中 ， 网 络 事件 的 触发 是 由 内 核 完 成 的 ， 内 核 如 果 文 持 epoll 束 可 以 使 用 
ngx_epoll _ module 模块 驱动 事件 ， 内 核 如 果 仅 文 持 select 那 就 得 使 用 ngx_select_ module 模 块 驱动 
事件 ， 定 时 器 事件 则 完全 是 由 Nginx 自 喘 实现 的 ， 它 与 内 核 完全 无 关 。 那 么 ， 所 有 事件 的 定 
时 需 是 如 何 组 织 起 来 的 呢 ? 在 事件 超时 后 ， 定 时 堪 是 如 何 触 发 事 件 的 呢 ? 读者 将 在 9.7.2 节 中 
看 到 定时 器 事件 的 设计 ， 但 首先 需要 和 弄 清 楚 Nginx 的 时 间 是 如 何 管理 的 。Nginx 与 一 般 的 服务 
器 不 同 ， 出 于 性 能 的 考虑 〈 不 需要 每 次 获取 时 间 都 调用 gettimeofday 方 法 ) ，Nginx 使 用 的 时 
间 是 缓存 在 其 内 存 中 的 ， 这 样 ， 在 Nginx 模 块 获取 时 间 时 ， 只 是 获取 内 存 中 的 儿 个 整 型 变量 
而 已 。 这 个 缓存 的 时 间 是 如 何 更 新 的 呢 ? 又 是 在 什么 时 刻 更 新 的 呢 ? 这 些 问题 读者 会 在 9.7.1 








9.7.1 缓存 时 间 的 管理 











Nginx 中 的 每 个 进程 都 会 单独 地 管理 当前 时 间 ， 下 面 来 看 一 下 缓存 的 全 局 时 间 变 量 是 什 
么 。ngx_time_t 结 构 体 是 缓存 时 间 变 量 的 类 型 ， 如 下 所 示 。 





typedef struct { 


// 格林 威 治 时 间 


1970 年 
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1 日 凌晨 


0 秒 到 当前 时 间 的 秒 数 


time t sec; 


// sec 成 员 只 能 精确 到 秒 ， 


msec 则 是 当前 时 间 相 对 于 


sec 的 毫秒 偏 移 量 


ngx uint t msec; 


// 时 区 


ngx_ int 七 gmtoff; 


http://ww | i nuxorobe. con 








可 以 看 到 ，ngx time 圳 精确 到 坚 秒 的 。 当 然 ，ngx_ time t 结 构 用 起 来 并 不 是 那么 方便 ， 
作为 Web 服 务 器 ， 很 多 时 候 要 用 到 可 读 性 较 强 的 规范 的 时 间 字 符 串 ， 因 此 ，Nginx 定 义 了 以 下 
全 局 变量 用 于 缓存 时 间 ， 代 人 码 如 下 。 











// 格林 威 治 时 间 


1970 年 


0 秒 到 当前 时 间 的 毫秒 数 


Volatile ngx msec t ngx current msec; // ngx time 七 结构 体形 式 的 当前 时 间 


vola 叶 下 4 ie 后 “下 和 fF htt po: // WA | 1 NUXxPr obe. con 





error 1og 的 当前 时 间 字 符 串 ， 它 的 格式 类 似 于 : 


了 97003728 12300300027 


Volatile ngx str t ngx cached err log time; /* 用 于 





HTTP 相 关 的 当前 时 间 字 符 串 ， 它 的 格式 类 似 于 : 


"Mon, 28 Sep 1970 06:00:00 GMT"*/ 


volatile ngx str t ngx cached http time; /* 用 于 记录 





HTTP 日 志 的 当前 时 间 字 符 串 ， 它 的 格式 类 似 于 : 


"28/Sep/1970:12:00:00 +0600"™*/ 


volatile ngx str t ngx cached http log time; // 以 





ISO 8601 标 准 格式 记录 下 的 字符 串 形式 的 当前 时 间 


volatile ngx str t ngx cached http log iso8601; 








Nginx 为 用 户 提供 了 6 种 当前 时 间 的 表示 形式 ， 这 已 经 足够 用 了 。Nginx 绥 存 时 间 的 操作 
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方法 见 表 9-4 所 示 。 


时 间 方 法 名 


void ngx_ time init(void); 


void ngx_time update(void) 


u char *ngx http_ time 
(u_char *buf, time tt) 


u char *ngx http_ cookie 
time(u_char *buf, time tt) 


void ngx gmtime 
(time tt, ngx tm t *tp) 





表 9-4 Neginx 缓 存 时 间 的 操作 方法 


执行 意义 


初始 化 当前 进程 中 缓存 的 时 间 变 量 ， 同 


无 时 会 第 一 次 根据 gettimeofday 调用 刷新 组 
存 时 间 


使 用 gettimeofday 调用 以 系统 时 间 更 新 
缓存 的 时 间 ， 上 述 的 ngx_current_msec、 
ngx cached time、 ngx cached err log 
time、 ngx cached http time、 ngx cached_ 
http_log time、 ngx cached http log_ 
iso8601 这 6 个 全 局 变量 都 会 得 到 更 新 


t 是 需要 转换 的 时 间 ， 它 是 格 
林 威 治 时 间 1970 年 1 月 1 日 凌晨 | 将 时 间 t 转 换 成 “Mon,28 Sep 1970 06:00:00 
0 点 0 分 0 秒 到 某 一 时 间 的 秒 数 , |GMT” 形 式 的 时 间 ， 返回 值 与 buf 是 相同 
buf 是 t 时 间 转 换 成 字符 串 形式 的 | 的 ， 都 是 指向 存放 时 间 的 字符 串 
HTTP 时 间 后 用 来 存放 字符 串 的 内 存 


t 是 需要 转换 的 时 间 ， 它 是 格 
林 威 治 时 间 1970 年 1 月 1 日 凌晨 | 将 时 间 t 转 换 成 “Mon, 28-Sep-70 06:00:00 
0 点 0 分 0 秒 到 某 一 时 间 的 秒 数 , |GMT ”形式 适 用 于 cookie 的 时 间 ， 返 回 值 
buf 是 t 时 间 转 换 成 字符 串 形 式 适 | 与 buf 是 相同 的 ， 都 是 指向 存放 时 间 的 字 
用 于 cookie 的 时 间 后 用 来 存放 字 | 符 串 
符 串 的 内 存 

t 是 需要 转换 的 时 间 ， 它 是 格林 
威 治 时 间 1970 年 1 月 1 日 凌晨 0 
点 0 分 0 秒 到 某 一 时 间 的 秒 数 ，tp 
是 ngx tm t 类 型 的 时 间 ， 实 际 上 
就 是 标准 的 tm 类 型 时 间 


将 时 间 t 转 换 成 ngx tm t 类 型 的 时 间 。 
下 面 会 说 明 ngx tm t 类 型 
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时 间 方 法 名 


time tngx next time 


(time t when) 


#define ngx_ time() 


ngx cached time->sec 


#define ngx timeofday() 


(ngex time t*)nex cached time 





执行 意义 

返回 -1 表示 失败 ， 和 否则 会 返回 : 由 如 果 
when 表示 当天 时 间 秒 数 ， 当 它 合并 到 实际 
时 间 后 ,已 经 超过 当前 时 间 ， 那么 就 返回 
when 合并 到 实际 时 间 后 的 秒 数 (相对 于 格 

when 表示 期 待 过 期 的 时 间 ， 它 | 林 威 治 时 间 1970 年 1 月 1 日 凌晨 0 点 0 分 
仅 表示 一 天 内 的 秒 数 0 秒 到 某 一 时 间 的 秒 数 ); 

加 反之 ， 如 果 合 并 后 的 时 间 早 于 当前 时 
间 ， 则 返回 下 一 天 的 同一 时 刻 (当天 时 刻 ) 
的 时 间 。 它 目前 仅 具 有 与 expires 配置 项 相 
关 的 缓存 过 期 功能 


无 获取 到 格林 威 治 时 间 1970 年 1 月 1 日 凌 
晨 0 点 0 分 0 秒 到 当前 时 间 的 秒 数 


获取 缓存 的 ngx_time t 类 型 时 间 


ngx_tm t 是 标准 的 tm 类 型 时 间 ， 下 面 完 看 一 下 tm 时 间 古 什么 样 的 ， 代 码 如 下 。 


struct tm { 


// 秒 


- 取 值 区 间 为 


[0,59] 
int tm sec; 
人 次 

- 取 值 区 间 为 
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[0,59] 
int tm min; 


// 时 


- 取 值 区 间 为 


[0,23] 
int tm hour; 


// 一 个 月 中 的 日 期 


- 取 值 区间 为 


[1,31] 
int tm mday; 


// 月 份 《 从 一 月 开始 ， 


0 代表 一 月 ) 


- 取 值 区 间 为 


[0,11] 
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int tm mon; 


// 年 份 ， 其 值 等 于 实际 年 份 减 去 


1900 
int tm year; 


// 星期 
- 取 值 区 间 为 
[0, 6] ， 其 中 
0 代表 星期 天 ， 


1 代表 星期 一 ， 依 此 类 推 


int tm wday; 


/* 从 每 年 的 


1 日 开始 的 天 数 
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- 取 值 区 间 为 


[0,365] ， 其 中 


0 代表 


1 代表 


2 日 ， 依 此 类 推 


int tm yday; 


/* 夏 令 时 标识 符 。 在 实行 夏令 时 的 时 候 ， 


tm_isdst 为 正 ; 不 实行 夏令 时 的 时 候 ， 
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tm isdst 为 


0; 在 不 了 解 情况 时 ， 


tm isdst 为 负 


int tm isdst; 





ngx_tm t 与 tm 用 法 古 完全 一 致 的 ， 如 下 所 示 。 





typedef struct tm ngx tm t; #define ngx tm sec tm sec #define ngx tm min tm m 





可 以 看 到 ，ngx_tm t 中 类 似 ngx_tm sec 这 样 的 成 员 与 tm sec 是 完全 一 致 的 。 


这 个 缓存 时 间 什 么 时 候 会 更 新 呢 ? 对 于 worker 进 程 而 言 ， 除 了 Nginx 局 动 时 更 新 一 次 时 
间 外 ， 任 何 更 新 时 间 的 操作 都 只 能 由 ngx_ epoll process_ events 方 法 (参见 9.6.3 节 ) 执行 。 回 
顾 一 下 ngx_epoll process_events 方 法 的 代码 ， 当 flags 参 数 中 有 NGX_UPDATE_TIME 标 志 位 ， 
或 者 ngx_event timer alarm 标 志 位 为 1 时 ， 就 会 调用 ngx_time update 方法 更 新 缓存 时 间 。 


9.7.2 ”缓存 时 间 的 精度 


上 文人 简单 地 介绍 过 缓存 时 间 的 更 新 策略 ， 它 是 与 ngx epoll process events 方 法 的 调用 频 
率 及 其 flag 参 数 相关 的 。 实 际 上 ，Nginx 还 提供 了 设置 更 新 缓存 时 间 频 率 的 功能 〈 也 就 是 至 少 
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隔 tmer _ resolution 坚 秒 必须 更 新 一 次 缓存 时 间 ) ， 通 过 在 nginx.conf 文 件 中 的 tmer resolution 
配置 项 可 以 设置 更 新 的 最 小 频率 ， 这 样 就 保证 了 绥 存 时 间 的 精度 。 


下 面 看 一 下 timer_resolution 是 如 何 起 作用 的 。 在 图 9-4 的 第 5 步 中 ，ngx_event core module 
模块 初始 化 时 会 使 用 setitimer 系 统 调用 告诉 内 核 每 隔 timer resolution 宇 秒 调用 一 次 
ngx timer signal handler 方 法 。 而 ngx timer signal handler 方 法 则 会 将 ngx_event timer alarm 标 
志 位 设 为 1， 这 样 一 来 ， 一 旦 调用 ngx epoll process events 方 法 ， 如 果 间 隔 的 时 间 超 过 


timer_ resolution 坚 秒 ， 肯 定 会 更 新 缓存 时 间 。 


但 如 果 很 久 都 不 调用 ngx epoll process_events 方 法 呢 ?” 例 如 ， 远 超过 timer _ resolution 毫秒 
的 时 间 内 ngx_epoll_process_events 方 法 都 得 不 到 调用 ， 那 时 间 精 度 如 何 保证 呢 ?” 在 这 种 情况 
下 ，Nginx 只 能 从 事件 模块 对 ngx_event_actions 中 process_events 接 口 的 实现 来 保证 时 间 精 度 
了 。process_events 方 法 的 第 2 个 参数 timer 表 示 收 集 事件 时 的 最 长 等 待 时 间 。 例 如 ， 在 epoll 模 
块 下 ， 这 个 timer 就 是 epoll_wait 调 用 时 传 入 的 超时 时 间 参 数 。 如 果 在 设置 了 timer_resolution 
后 ， 这 个 timer 参 数 就 是 -1， 它 表示 如 果 epoll wait 等 调用 检测 不 到 已 经 发 生 的 事件 ， 将 不 等 
待 而 是 立刻 返回 ， 这 样 就 控制 了 时 间 精 度 。 当 然 ， 如 果菜 个 事件 消费 模块 的 回调 方法 执行 时 
占用 的 时 间 过 长 ， 时 间 精 度 还 是 难以 得 到 保证 的 。 











9.7.3 ”定时 器 的 实现 


定时 器 是 通过 一 棵 红 黑 树 实现 的 。ngx event timer rbtree 就 是 所 有 定时 器 事件 组 成 的 红 


黑 树 ， 而 ngx_event timer_sentinel 就 是 这 棵 红 黑 树 的 哨兵 节点 ， 如 下 所 示 。 





ngx thread Volatile ngx rbtree t ngx event timer rbtree; static ngx rbtree node t ngx event timer sentinel; 























这 棵 红 黑 树 中 的 每 个 节点 都 是 ngx event t 事 件 中 的 timer 成 员 ， 而 ngx_rbtree_node t 节 点 的 
关键 字 就 是 事件 的 超时 时 间 ， 以 这 个 超时 时 间 的 大 小 组 成 了 二 又 排序 树 
ngx_event timer Tbtree。 这 样 ， 如 果 需 要 找 出 最 有 可 能 超时 的 事件 ， 那 么 将 
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ngx_event timer Tbtree 树 中 最 左边 的 节点 取出 来 即 可 。 只 要 用 当前 时 间 去 比较 这 个 最 左边 节 
点 的 超时 时 间 ， 就 会 知道 这 个 事件 有 没有 触发 超时 ， 如 果 还 没有 触发 超时 ， 那 么 会 知道 最 少 
还 要 经 过 多 少 毫秒 满足 超时 条 件 而 触发 超时 。 先 看 一 下 定时 器 的 操作 方法 ， 见 表 9-5。 


表 9-5 定时 器 的 操作 方法 


方法 名 参数 含义 执行 意义 
ngx int tngx event timer init log 是 可 以 记录 日 志 的 ngx_ 





思 始 化 定时 中 
(ngx_log t *log): log t 对 象 加 巡 化 定时 六 





找 出 红 黑 树 中 最 左边 的 节点 ， 如 果 它 的 超 
时 时 间 大 于 当前 时 间 ， 也 就 表明 目前 的 定时 
oe 有 一 个 事件 满足 触发 条 件 ， | 
无 这 个 超时 与 当前 时 间 的 差 值 ， 也 就 是 需要 
过 笑 es 会 有 事件 超时 触发 ; 如 果 它 的 起 
时 时 间 小 Tm 各 于 当前 时 间 ， 则 返回 0， 表 
示 定 时 器 中 已 经 存在 超时 需要 触发 的 事件 
丛 查 定时 器 中 的 所 有 事件 ， 按照 红 黑 树 关 关 
无 键 字 由 小 到 大 的 顺序 依次 调用 已 经 满足 超时 
条 件 需 要 被 触发 事件 的 handler 回 训 方法 


ngx msec tngx event find 


timer(vo1id): 


Vold ngx event expire 





timers(vo1d): 





static ngx_inline Vold 

ngx event del timer ev 是 需要 操作 的 事件 从 定时 需 中 移 除 一 个 事件 

(ngx_ event t *ev) 
ev 是 需要 操作 的 事件 ,timer 

的 单位 是 毫秒 ， 它 告诉 定时 需 事 | 添 个 定时 器 事件 ， 超 时 时 间 为 timer 

件 ev 希望 timer 上 毫秒 后 超时 ， 同 | 毫秒 

时 需要 回调 ev 的 handler 方法 


static nex_inline Vold 
ngx event add timer(ngx_ 


event t *ev, ngx msec t timer) 


事实 上 ， 还 有 两 个 宏 与 ngx_event add timer 方 法 和 ngx event del timer 方 法 的 用 法 是 完全 
一 样 的 ， 如 下 所 示 。 








#define ngx add timer ngx event add timer #define ngx del timer ngx event del timer 





从 表 9-5 可 以 看 出 ， 只 要 调用 ngx event expire timers 方 法 就 可 以 触发 所 有 超时 的 事件 ， 
在 这 个 方法 中 ， 循 环 调用 所 有 满足 超时 条 件 的 事件 的 handler 回 调 方法 。 那 么 ， 多 入 调用 一 次 
ngx event expire timers 方 法 呢 ? 这 个 时 间 频 率 可 以 部 分 参照 hgx event find timer 方 法 ， 因 为 


ngx_event find_timer 会 告诉 用 户 下 一 个 最 近 的 超时 事件 多 久 后 会 发 生 。 
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在 9.8.5 节 中 ， 读 者 会 看 到 ngx event expire_timers 究 竟 什 么 时 候 会 被 调用 。 
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9.8 ”事件 驱动 框架 的 人 处理 流程 


本 节 开 始 讨论 事件 处 理 流程 。 在 9.5.1 节 中 已 经 看 到 ， 图 9-4 的 第 12 步 会 将 监听 连接 的 读 
事件 设 为 ngx event accept 方 法 ， 在 第 13 步 会 把 监听 连接 的 读 事件 添加 到 ngx_epoll module 事 
件 驱 动 模块 中 。 这 样 ， 在 执行 hgx epoll process events 方 法 时 ， 如 果 有 新 连接 事件 出 现 ， 则 
会 调用 ngx event accept 方 法 来 建立 新 连接 。 在 9.8.1 节 中 将 会 讨论 ngx event accept 方法 的 执行 





流程 。 





当然 ， 建 并 连接 其 实 没有 那么 简单 。Nginx 出 于 充分 发 挥 多 核 CPU 染 构 性 能 的 考虑 ， 使 
用 了 多 个 worker 子 进程 监听 相同 端口 的 设计 ， 这 样 多 个 子 进程 在 accept 建 立新 连接 时 会 有 争 
抢 ， 这 会 带 来 著名 的 “ 惊 群 ?问题 ， 子 进程 数量 越 多 问题 越 明 显 ， 这 会 造成 系统 性 能 下 降 。 在 
9.8.2 市 中 ， 我 们 会 讲 到 在 建立 新 连接 时 Nginx 是 如 何 避 免 出 现 “ 尺 群 * 现 象 的 。 





为 外 ， 建 立 连接 时 还 会 涉及 负载 均衡 问题 。 在 多 个 子 进程 争 抢 处 理 一 个 新 连接 事件 时 ， 
一 定 只 有 一 个 worker 子 进程 最 终 会 成 功 建立 连接， 随后 ， 它 会 一 直 处 理 这 个 连接 直到 连接 天 
闭 。 那 么 ， 如 果 有 的 子 进程 很 “勤奋 ”"， 它 们 抢 闭 建立 并 处 理 了 大 部 分 连接 ， 而 有 的 子 进 程 
则 “运气 不 好 ?， 只 处 理 了 少量 连接 ， 这 对 多 核 CPU 架构 下 的 应 用 是 很 不 利 的 ， 因 为 子 进程 间 
应 该 是 平等 的 ， 每 个 子 进程 应 该 尽量 地 独占 一 个 CPU 核心 。 子 进程 间 负 载 不 均衡 ， 必 然 影响 
整个 服务 的 性 能 。 在 9.8.3 节 中 ， 我 们 会 看 到 Nginx 是 如 何 解 决 负载 均衡 问题 的 。 














实际 上 ， 上 述 问 题 的 解决 离 不 开 Nginx 的 post 事 件 处 理 机 制 。 这 个 post 事 件 是 什么 意思 
呢 ? 它 表示 允许 事件 延 后 执行 。Nginx 设 计 了 两 个 post 队 列 ， 一 个 是 由 被 触发 的 监听 连接 的 读 
事件 构成 的 ngx_posted_accept_events 队 列 ， 另 一 个 是 由 普通 读 / 写 事件 构成 的 
ngx_posted_events 队 列 。 这 样 的 post 事 件 可 以 让 用 户 完 成 什么 样 的 功能 呢 ? 


将 epoll_wait 产 生 的 一 批 事件 ， 分 到 这 两 个 队列 中 ， 让 存放 着 新 连接 事件 的 


ngx_bosted_accept_events 队 列 优先 执行 ， 存 放 普 通 事 件 的 ngx_ posted_events 队 列 最 后 执行 ， 这 
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是 解决 “ 惊 群 ”和 负载 均衡 两 个 问题 的 关键 。 


` 如 果 在 处 理 一 个 事件 的 过 程 中 产生 了 另 一 个 事件 ， 而 我 们 希望 这 个 事件 随后 执行 (不 
立刻 执行 ) ， 就 可 以 把 它 放 到 post 队 列 中 。 在 9.8.3 节 中 会 介绍 post 队 列 。 


部 


我 们 在 9.8.5 节 中 将 本 章 的 网 络 事件 、 定 时 器 事件 进行 综合 考虑 ， 以 说 明 
ngx_process_events_and_timers 事 件 框 架 执行 流程 是 如 何 把 连接 的 建立 、 事 件 的 执行 结合 在 一 
起 的 。 


9.8.1 如 何 建立 新 连接 


上 文 提 到 过 ， 处 理 新 连接 事件 的 回调 函数 是 ngx_event_ accept， 其 原型 如 下 。 





void ngx event accept (ngx event 七 *ev) 





下 面 简单 介绍 一 下 它 的 流程 ， 如 图 9-6 所 示 。 
下 面 对 访 程 中 的 7 个 步骤 进行 说 明 。 


1) 首先 调用 accep 坊 法 试图 建立 新 连接 ， 如 果 没 有 准备 好 的 新 连接 事件 ， 
ngx_event accept 方法 会 直接 返回 。 


2) 设置 负载 均衡 国 值 ngx accept disabled， 这 个 国 值 是 进程 允许 的 总 连接 数 的 1/8 减 去 空 
朵 连接 数 ， 它 的 有 具体 用 法 参见 9.8.3 节 。 
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1 ) 调 用 accep 访 法 建立 新 的 
TCP 连 # 
[成 功 建立 TCP 连 接 ] 


2) 设 置 负 载 均 衡 国 值 


ngx_accept_disable 






3) 由 连接 池 中 获取 一 
ngx_connec tion 本体 


| 


[没有 新 连接 可 建立 ] 的 属性 













[available 标志 位 为 1] 





6) 将 这 PX 新 连 各 的 尖 于 什 深 加 到 


epoll 





7) 调 用 ! 监听 端口 上 ngx distoning t 结构 体 的 
handler 方 法 处 理 新 连接 


[检查 监听 连接 读 事件 的 available 标 志 





available 为 0] 
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图 9-6 ”ngx_event_accept 方 法 建立 新 连接 的 流程 
3) 调用 ngx_get_connection 方 法 由 连接 池 中 获取 一 个 ngx_connection t 连 接 对 象 。 


4) 为 ngx_connection t 中 的 pool 指 针 建 立 内 存 池 。 在 这 个 连接 释放 到 空 闪 连接 池 时 ， 释 放 
pool 内 存 池 。 


5) 设置 套 接 字 的 属性 ， 如 设 为 非 阻塞 套 接 字 。 


6) 将 这 个 新 连接 对 应 的 读 事件 添加 到 epoll 等 事件 驱动 模块 中 ， 这 样 ， 在 这 个 连接 上 如 
果 接收 到 用 户 请 求 epoll_wait， 就 会 收集 到 这 个 事件 。 


7) 调用 监听 对 象 ngx listening t 中 的 handler 回 调 方法 。ngx_listening t 结 构 体 的 handler 回 
调 方 法 就 是 当 新 的 TCP 连 接 刚 刚 建立 完成 时 在 这 里 调用 的 。 








最 后 ， 如 果 监 听 事 件 的 available 标 志 位 为 1， 再 次 循环 到 第 1 步 ， 否 则 ngx_event accept 方 
法 结束 。 事 件 的 available 标 志 位 对 应 着 multi accept 配 置 项 。 当 available 为 时， 告诉 Nginx 一 
次 性 尽量 多 地 建立 新 连接 ， 它 的 实现 原理 也 就 在 这 里 。 


9.8.2 ”如 何 解决 “ 际 群 ?问题 


只 有 打开 了 accept_mutex 锁 ， 才 可 以 解决 “ 惊 群 "问题 。 何 谓 “ 惊 群 "? 惑 像 上 面 说 过 的 那 
样 ，master 进 程 开始 监听 Web 端 口 ，fork 出 多 个 worker 子 进程 ， 这 些 子 进程 开始 同时 监听 同一 
个 Web 端 口 。 一 般 情 况 下 ， 有 多 少 CPU 核 心 ， 就 会 配置 多 少 个 worker 子 进程 ， 这 样 所 有 的 
worker 子 进程 都 在 承担 着 Web 服 务 器 的 角色 。 在 这 种 情况 下 ， 就 可 以 利用 每 一 个 CPU 核心 可 
以 并 发 工作 的 特性 ， 充 分 发 挥 多 核 机 器 的 “威力 ”。 但 下 面 假定 这 样 一 个 场景 : 没有 用 户 连 入 
服务 器 ， 某 一 时 刻 恰好 所 有 的 worker 子 进程 都 休眠 且 等 待 新 连接 的 系统 调用 《如 
epoll wait) ， 这 时 有 一 个 用 户 向 服务 器 发 起 了 连接 ， 内 核 在 收 到 TCP 的 SYN 包 时 ， 会 激活 所 


有 的 休 虐 worker 子 进程 ， 当 然 ， 此 时 只 有 最 先 开始 执行 accept 的 子 进程 可 以 成 功 建立 新 连 
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接 ， 而 其 他 worker 子 进程 都 会 accept 失 败 。 这 些 accept 失 败 的 子 进 程 被 内 核 唤 醒 是 不 必要 的 ， 
它们 被 唤醒 后 的 执行 很 可 能 也 是 多 余 的 ， 那 么 这 一 时 刻 它 们 占用 了 本 不 需要 占用 的 系统 资 
源 ， 引 发 了 不 必要 的 进程 上 下 文 切换 ， 增 加 了 系统 开销 。 








也 许 很 多 操作 系统 的 最 新 版 本 的 内 核 已 经 在 事件 驱动 机 制 中 解决 了 惊 群 ?问题 ， 但 
Nginx 作 为 可 移植 性 极 高 的 Web 服 务 器 ， 还 是 在 上 自身 的 应 用 层面 上 较 好 地 解决 了 这 一 问题 。 既 
然 “ 恢 群 ?是 多 个 子 进程 在 同一 时 刻 监听 同一 个 端口 引起 的 ， 那 么 Nginx 的 解雇 方式 也 很 简 
单 ， 它 规定 了 同一 时 刻 只 能 有 唯一 一 个 worker 子 进程 监听 Web 端 口 ， 这 样 就 不 会 发 生 “ 惊 
群 " 了 ， 此 时 新 连接 事件 只 能 唤醒 唯一 正在 监听 端口 的 worker 子 进程 。 


可 是 如 何 限制 在 某 一 时 刻 仅 能 有 一 个 子 进程 监听 Web 端 口 呢 ? 下面 看 一 下 
ngx_trylock _ accept mutex 方 法 的 实现 。 在 打开 accept_ mutex 锁 的 情况 下 ， 只 有 调用 
ngx trylock accept mutex 方 法 后 ， 当 前 的 worker 进 程 才 会 去 试 着 监听 web 端 口 ， 具 体 实 现 如 下 
所 示 。 





ngx int t ngx trylock accept mutex(ngx cycle t *cycle) 


/* 使 用 进程 间 的 同步 锁 ， 试 图 获取 
accept mutex 锁 。 注 意 ， 
ngx_shmtx tryYLock 返 回 
1 表示 成 功 拿 到 锁 ， 返 回 
0 表示 获取 锁 失 败 。 这 个 获取 和 锁 的 过 程 是 非 阻塞 的 ， 此 时 一 旦 锁 被 其 他 
worker 子 进程 占用 ， 
ngx shmtx trylock 方 法 会 立刻 返回 ( 详 见 


14:8 节 ) 


if (ngx shmtx tryJock(&ngx accept mutex)) f{ 
如 果 获 取 到 


accept mutex 锁 ， 但 
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ngx _ accept mutex held 为 





1 ， 则 立刻 返回 。 


ngx accept mutex held 是 一 个 标志 位 ， 当 它 为 





1 时 ， 表 示 当 前 进程 已 经 获取 到 锁 了 


wy 
if (ngx accept mutex held 
&& ngx accept events == 
&& !(ngx event flags & NGX USE RTSIG EVENT)) 








// ngx accept mutex 锁 之 前 已 经 获取 到 了 ， 立 刻 返 回 


return NGX OK; 
i 
// 将 所 有 监听 连接 的 读 事件 添加 到 当前 的 


epoll 等 事件 驱动 模块 中 


if (ngx enable accept events(cycle) == NGX ERROR) { 
/* 既 然 将 监听 句柄 添加 到 事件 驱动 模块 失败 ， 就 必须 释放 











ngx accept mutex 锁 


ngx shmtx unlock (&ngx accept mutex); 
return NGX ERROR; 


ngx_enable_accept_events 方 法 的 调用 ， 当 前 进程 的 事件 驱动 模块 已 经 开始 监听 所 有 的 端口 ， 这 时 需要 把 








ngx accept mutex held 标 志 位 置 为 





1， 方 便 本 进程 的 其 他 模块 了 解 它 目前 已 经 获取 到 了 锁 


ngx accept events = 0; 
ngx accept mutex held = 1; 
return NGX OK; 





} 
如 果 


ngx_shmtx trylock 返 回 
0， 则 表明 获取 
ngx_accept mutex 锁 失败 ， 这 时 如 果 


ngx accept mutex _ held 标志 位 还 为 
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if (ngx accept mutex held) 1 
ngx disable accept _events 会 将 所 有 监听 连接 的 读 事 件 从 事件 驱动 模块 中 移 除 








if (ngx disable accept events (cycle) == NGX ERROR) 了 
return NGX ERROR; 


ngx_accept _mutex 锁 时 ， 必 须 把 


ngx accept mutex held 置 为 





DY 
ngx _ accept mutex held = 0; 
} 
return NGX OK; 








} 





在 上 面 关 于 ngx_trylock accept_ mnutex 方 法 的 源 代 码 中 ，ngx_accept mutex 实 际 上 是 Nginx 进 
程 间 的 同步 锁 。 第 14 章 我 们 会 详细 介绍 进程 间 的 同步 方式 ， 目 前 只 需要 清楚 
ngx_shmtx trylock 方 法 是 一 个 非 阻塞 的 获取 锁 的 方法 即 可 。 如 果 成 功 获取 到 锁 ， 则 返回 1， 合 
则 返回 0。nsgx shmtx unlock 方 法 负责 释放 锁 。ngx accept mutex held 是 当前 进程 的 一 个 全 局 变 
量 ， 如 果 为 1， 则 表示 这 个 进程 已 经 获取 到 了 ngx _ accept mutex 锁 ;如果 为 0， 则 表示 没有 获 
取 到 锁 ， 这 个 标志 位 主要 用 于 进程 内 各 模块 了 解 是 否 获 取 到 了 ngx accept mutex 锁 ， 有 具体 定 
义 如 下 所 示 。 











ngx_ shmtx 七 ngx accept mutex; 
ngx Wint: t ngx accept mutex held; 








因此 ， 在 调用 ngx_trylock_accept_mutex 方 法 后 ， 要 么 是 唯一 获取 到 ngx_accept_mutex 锁 且 
其 epoll 等 事件 驱动 模块 开始 监控 Web 端 口上 的 新 连接 事件 ， 要 么 是 没有 获取 到 锁 ， 当 前 进程 
不 会 收 到 新 连接 事件 。 





如 果 nsgx_trylock_ accept mnutex 方 法 没有 获取 到 锁 ， 接 下 来 调用 事件 驱动 模块 的 
process_events 方 法 时 只 能 处 理 已 有 的 连接 上 的 事件 ， 如 果 获 取 到 了 锁 ， 调 用 process_events 方 


法 时 就 会 既 处 理 已 有 连接 上 的 事件 ， 也 处 理 新 连接 的 事件 。 这 样 的 话 ， 问 题 又 来 了 ， 什 么 时 
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候 释 放 ngx accept_ mutex 锁 昵 ? 等 到 这 批 事件 全 部 执行 完 吗 ? 这 当然 是 不 可 取 的 ， 因 为 这 个 
worker 进 程 上 可 能 有 许多 活跃 的 连接 ， 处 理 这 些 连接 上 的 事件 会 占用 很 长 时 间 ， 也 就 是 说 ， 
会 有 很 长 时 间 都 没有 释放 nsgx accept mutex 锁 ， 这 样 ， 其 他 worker 进 程 就 很 难得 到 处 理 新 连接 
的 机 会 。 





如 何 解雇 长 时 间 占 用 ngx_accept_ mutex 锁 的 问题 呢 ? 这 就 要 依靠 ngx posted_accept_events 
队列 和 ngx_ posted_events 队 列 了 。 首 先 看 下 面 这 段 代 码 : 








if (ngx trylock _ accept mutex (Cycle) == NGX ERROR) { 
return; 





} 
if (ngx accept mutex held) { 
flags |= NGX POST EVENTS; 

















} 








调用 ngx_trylock_accept_mutex 试 图 处 理 监听 端口 的 新 连接 事件 ， 如 果 
ngx_accept_mutex_held 为 1， 就 表示 开始 处 理 新 连接 事件 了 ， 这 时 将 flags 标 志 位 加 上 
NGX POST_EVENTS。 这 里 的 flags 是 在 9.6.3 市 中 列举 的 ngx_epoll_process_events 方 法 中 的 第 3 
个 参数 flags。 回 顾 一 下 这 个 方法 中 的 代码 ， 当 flags 标 志 位 包含 NGX POST_ EVENTS 时 是 不 会 
立刻 调用 事件 的 handler 回 调 方法 的 ， 代 码 如 下 所 示 。 





if ((revents & EPOLLIN) && rev->active) { 
if (flags & NGX POST EVENTS) { 
queue = (ngx event 七 **) (rev->accept &ngx posted accept events : &ngx posted events); 
ngx_ locked post event (rev, queue); 
} else { 
rev->handler (rev); 


} 


























} 





对 于 写 事件 ， 也 可 以 采用 同样 的 处 理 方法 。 实 际 上 ，ngx_posted accept_events 队 列 和 
ngx_posted_events 队 列 把 这 批 事 件 归 类 了 ， 即 新 连接 事件 全 部 放 到 ngx_posted_accept_events 队 
列 中 ， 普 通 事件 则 放 到 ngx_posted_events 队 列 中 。 这 样 ， 接 下 来 会 先 处 理 
ngx_posted_accept_events 队 列 中 的 事件 ， 处 理 完 后 就 要 立刻 释放 ngx_accept mutex 锁 ， 接 着 再 
处 理 ngx_posted_events 队 列 中 的 事件 (参见 图 9-7) ， 这 样 就 大 大 减少 了 ngx accept mutex 锁 占 
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9.8.3 ”如何 实现 负载 均衡 


与 “ 惊 群 ?问题 的 解决 方法 一 样 ， 只 有 打开 了 accept mutex 锁 ， 才 能 实现 worker 子 进程 间 的 
负载 均衡 。 在 图 9-6 的 第 2 步 中 ， 初 始 化 了 一 个 全 局 变量 ngx _ accept disabled， 它 就 是 负载 均衡 
机 制 实现 的 关键 浆 值 ， 实 际 上 它 就 是 一 个 整 型 数据 。 





ngx int 七 ngx accept disabled; 





这 个 闹 值 是 与 连接 池 中 连接 的 使 用 情况 密切 相关 的 ， 在 图 9-6 的 第 2 步 中 它 会 进行 赋值 ， 
如 下 所 示 。 





ngx accept disabled = ngx cycle->connection n/8 
- ngx cycle->free connection n; 





因此 ， 在 Nginx 启 动 时 ，ngx accept_disabled 的 值 就 是 一 个 负数 ， 其 值 为 连接 总 数 的 7/8。 
其 实 ，ngx_accept_disabled 的 用 法 很 简单 ， 当 它 为 负数 时 ， 不 会 进行 触发 负载 均衡 操作 ;而 
当 ngx_accept_ disabled 是 正 数 时 ， 就 会 触发 Neginx 进 行 负载 均衡 操作 了 。Nsginx 的 做 法 也 很 简 
单 ， 就 是 当 ngx _ accept _ disabled 是 正 数 时 当前 进程 将 不 再 处 理 新 连接 事件 ， 取 而 代 之 的 仅仅 
是 ngx accept disabled 值 减 1， 如 下 所 示 。 





if (ngx _ accept disabled > 0) { 
ngx _ accept disabled--; 
} else { 
if (ngx trylock accept mutex (Cycle) == NGX ERROR) { 
return; 








} 





上 面 这 段 代 码 表 明 ， 在 当前 使 用 的 连接 到 达 总 连接 数 的 7/8 时 ， 束 不 会 再 处 理 新 连接 
了 ， 同 时 ， 在 每 次 调用 process_events 时 都 会 将 ngx accept _ disabled 减 1， 直 到 


ngx accept disabled 降 到 总 连接 数 的 7/8 以 Ti [re 月 用 ngx - Vi accept _ 图 去 处 理 
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新 连接 事件 。 


此 ，Nginx 各 worker 子 进程 间 的 负载 均衡 仅 在 茶 个 worker 进 程 处 理 的 连接 数 达 到 它 最 大 
处 理 总 数 的 7/8 时 才 会 触发 ， 这 时 该 worker 进 程 就 会 减少 处 理 新 连接 的 机 会 ， 这 样 其 他 较 空 内 
的 worker 进 程 就 有 机 会 去 处 理 更 多 的 新 连接 ， 以 此 达到 整个 Web 服 务 的 均衡 处 理 效 果 。 虽 然 
这 样 的 机 制 不 是 很 完美 ， 但 在 维护 一 定 程度 上 的 负载 均衡 时 ， 很 好 地 避免 了 当 某 个 worker 进 
程 由 于 连接 池 耗 尽 而 拒绝 服务 ， 同 时 ， 在 其 他 worker 进 程 上 处 理 的 连接 还 远 未 达到 上 限 的 问 





题 。 因 此 ，Nsginx 将 accept mutex 配 置 项 默认 设 为 accept mutex on。 


9.8.4 ” post 事件 队列 


上 文 已 经 介绍 过 post 事 件 的 意义 ， 本 市 来 看 一 下 post 事 件 处 理 的 实现 方法 。 下 面 是 两 个 
post 事 件 队 列 的 定义 : 


ngx thread Volatile ngx event t ngx posted accept events; 
ngx thread volatile ngx event t ngx posted events; 











这 两 个 指针 都 指 辐 事件 队列 中 的 首 个 事件 。 这 些 事 件 间 是 以 双 同 链表 的 形式 组 织 成 post 
事件 队列 的 。 注 意 ，9.2 节 中 ngx event t 结 构 体 的 nextfIprev 成 员 仪 用 于 post 事 件 队列 。 





对 于 post 事 件 队 列 的 操作 方法 共有 4 个 ， 见 表 9-6。 


在 9.6.3 节 中 已 经 介绍 过 ngx post_event 方 法 的 应 用 ， 它 会 将 事件 添加 到 队列 中 ， 那 么 ， 
post 事 件 什 么 时 候 会 执行 呢 ? 在 9.8.5 节 我 们 就 会 介绍 ngx_event process_posted 是 如 何 被 调用 
的 。 


表 9-6 post 事 件 队 列 的 操作 方法 
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方法 名 执行 意义 

ev 是 要 添加 到 post 事件 队列 的 | 回 queue 事 件 队 列 中 添加 事件 ev， 注 
事件 ，queue 是 post 事件 队列 意 ，ev 将 插入 到 事件 队列 的 首部 

线程 安全 地 回 queue 事件 队列 中 添加 事 
件 ev。 在 日 前 不 使 用 多 线程 的 情况 下 ， 它 
与 ngx_ locked_post_event 的 功能 是 相同 的 

ev 是 要 从 某 个 post 事 件 队 列 移 | 将 事件 ev 从 其 所 属 的 post 事 件 队列 中 
除 的 事件 删除 

cycle 是 进程 的 核心 结构 体 ngx_ 
void ngx_event_process_posted |cycle t 的 指针 ，posted 是 要 操作 的 


ngx locked post event(ev, queue) 


ev 是 要 添加 到 post 队列 的 事件 ， 


ngx post event(ev, queue) 人 
queue 是 post 事件 队列 


ngx_delete posted event(ev) 





调用 posted 事 件 队 列 中 所 有 事件 的 
(ngx_cycle t *cycle,ngx_thread_|post 事件 队列 ， 它 的 取 值 目前 仅 可 | handler 回调 方法 。 每 个 事件 调用 完 handler 
volatile ngx event t **posted): 以 为 ngx posted_events 或 者 ngx | 方法 后 ， 就 会 从 posted 事件 队列 中 删除 


posted_accept_events 


9.8.5 ngx process_events_and_timers 流 程 


本 市 将 综合 上 文 相关 内 容 ， 探 讨 Nginx 事 件 框架 处 理 的 流程 。 


在 图 8-7 中 ， 每 个 worker 进 程 都 在 ngx worker process_cycle 方 法 中 循环 处 理事 件 。 图 8-7 
中 的 处 理 分 发 事件 实际 上 就 是 调用 的 ngx process_events_and timers 方 法 ， 下 面 先 看 一 下 它 的 
定义 : 





void ngx process events and timers (ngx cycle t *cycle); 





循环 调用 ngx_process_events_and_timers 方 法 就 是 在 处 理 所 有 的 事件 ， 这 正 是 事件 驱动 机 
制 的 核心 。 顾 名 思 义 ，ngx_process_ events and timers 方 法 既 会 处 理 普 通 的 网 络 事件 ， 也 会 处 
理 定 时 器 事件 ， 在 图 9-7 中 ， 读 者 会 看 到 在 这 个 方法 中 到 底 做 了 哪些 事情 。 





ngx_process_events_and_timers 方 法 中 核心 的 操作 主要 有 以 下 3 个 : 
* 调用 所 使 用 的 事件 驱动 模块 实现 的 pfocess_evenhts 方 法 ， 处 理 网 络 事件 。 


: 处 理 两 个 post 事 件 队 列 中 的 事件 ， 实 际 上 就 是 分 别 调用 


ngx_event_process_posted(cycle,&npgx_posted_accept_events) 和 
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ngx_event_process_posted(cycle,&ngx_posted_events) 方 法 (参见 9.8.4 节 ) 。 
. 处 理 定 时 器 事件 ， 实 际 上 就 是 调用 nex_event_expite_timets0 方 法 〈 参 见 9.7.3 节 ) 。 


后 两 项 操作 很 清晰 ， 而 调用 事件 驱动 模块 的 process_events 方 法 时 则 需要 设置 两 个 关键 参 
数 timer 和 flags。Nginx 用 一 系列 宏 封 装 了 ngx event actions 接 口中 的 方法 ， 如 下 所 示 。 





#define ngx process changes ngx event actions.process changes 





#define ngx process events ngx event actions.process events 
#define ngx done events ngx event actions.done 

#define ngx aqq event ngx event actions.add 

#define ngx del event ngx event actions.del 

#define ngx add conn ngx event actions.add conn 
#define ngx del conn ngx event actions.del conn 
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[使 用 Hmer_resolutionl 







1 )timer 参 数 设 置 
-1l,flags 参数 设置 为 0 
[tmer_resolution 未 使 用 ] 


丸 行 ngx_event_find_timer 


2) 忆 
得 到 最 近 超时 ne、 并 将 flags 设 置 为 NGX_UPDATE_TIME 
[检查 accept_mutex 锁 是 否 开 启 ] 










[accept_mutex 怨 i 打 开 ] 


ngx_accept_disabled >0 
[ngx-accept- 3 ) ngx accept disabled 





[不 使 用 accept _mutex 锁 ][ngx_accept_disabled <= 0 未 触发 负载 均衡 ] 


4) 贡 用 ngx_trylock_accept_ 
mutex 试图 获取 accept _mutex 锁 
[检查 是 否 获取 到 了 atcept mutex 锁 ] 
ngx_accept_mutex_held 为 1 表示 持 有 J 了 accept_mutex 锁 ] 





[ngx_accept_mutex_held 为 0 表示 未 持 有 accept_mutex 锁 ] 


6) 将 timer 设 置 为 5 ) 将 flags 加 入 NGX_POST_ 
ngx_accept_mutex_delay EVENTS 标 志 位 


7 ) 调 用 ngx_process _events 方法， 
并 计算 出 耗 时 delta 





ngx_ posted_accept_events 队列 中 有 事件 ] 


[ngx_posted_accept events 队 列 为 空 8 ) 执 行 ngx_posted_accept_events 
Ss . 队列 中 的 事件 





[ngx_accept_mutex_held 为 1 表示 持 有 了 锁 ] 
C2 UY 
9 ) 调 用 ngx_shmtx_unlock 
释放 accept_mutex 锁 





[ngx_accept_mutex_held 为 0] 


[ngx_process _events 方 法 耗 时 delta >0] 
2 N 
10) 调用 ngx_event_expire_timers 


[delta=0] 执行 所 有 超时 事件 


中 11) 执 行 a ‘vents 
[ngx_posted_events 队列 为 空 ] A Tee oy 





[ngx_posted_events 队列 中 有 事件 ] 
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图 9-7 ngx_process_events_and_timers 方 法 中 的 事件 框架 处 理 流程 


在 调用 ngx process_events 时 ， 传 入 的 timer 和 flags 会 影响 时 间 精 度 以 及 事件 是 否 会 在 post 
队列 中 处 理 。 下 面 简要 分 析 一 下 图 9-7 中 的 11 个 步骤 ， 其 中 前 6 个 步骤 都 与 参数 timer 和 flags 的 
设置 有 关 。 


1 ) 如 果 配 置 文件 中 使 用 了 timer_resolution 配 置 项 ， 也 就 是 ngx_timer resolution 值 大 于 0， 
则 说 明 用 户 希 望 服务 器 时 间 精 确 度 为 nex timer resolution 毫 秒 。 这 时 ， 将 ngx process_events 
的 timer 参 数 设 为 -1， 告 诉 ngx_process_events 方 法 在 检测 事件 时 不 要 等 待 ， 直 接 搜集 所 有 已 经 
就 绪 的 事件 然后 返回 ， 同 时 将 fags 参 数 初始 化 为 0， 它 是 在 告诉 ngx_process_events 没 有 任何 
附加 动作 。 





2) 如 果 没 有 使 用 timer_resolution， 那 么 将 调用 ngx event find timer() 方 法 (参见 表 9-5) 
获取 最 近 一 个 将 要 触发 的 事件 距离 现在 有 多 少 蜡 秒 ， 然 后 把 这 个 值 赋予 tmer 参 数 ， 告 诉 
ngx_process_events 方 法 在 检测 事件 时 如 果 没 有 任何 事件 ， 最 多 等 竺 timer 晤 秒 就 返回 将 flags 
参数 设置 为 NGX UPDATE TIME， 告 诉 ngx process events 方 法 更 新 缓存 的 时 间 (参见 9.6.3 节 











中 ngx epoll process_events 方 法 的 源 代 码 ) 。 


3) 如 果 在 配置 文件 中 使 用 accept mutex off 关 闭 accept mutex 锁 ， 束 直接 跳 到 第 7 步 ， 否 则 
检测 负载 均衡 闷 值 变量 ngx accept disabled。 如 果 ngx accept _ disabled 是 正 数 ， 则 将 其 值 减 去 
1， 继 续 同 下 执行 第 7 步 。 


4) 如 果 ngx_accept_disabled 是 负数 ， 表 明 还 没有 触发 到 负载 均衡 机 制 ( 参 见 9.8.3 节 )， 
此 时 要 调用 ngx trylock_accept_mutex 方 法 试图 去 获取 accept_mutex 锁 (也 就 是 ngx accept_mutex 
变量 表示 的 锁 ) 。 


5) 如 果 获 取 到 accept mutex 锁 ， 也 就 是 说 ，ngx accept mutex_ held 标志 位 为 1， 那 么 将 
flags 人 参数 加 上 NGX POST_ EVENTS 标志 ， 告 诉 ngx process_events 方 法 搜集 到 的 事件 没有 直接 
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执行 它 的 handler 方 法 ， 而 是 分 门 别 类 地 放 到 ngx posted_accept_ events 队 列 和 ngx_posted_events 
队列 中 。timer 参 数 保持 不 变 。 


6) 如 果 没 有 获取 到 accept mutex 锁 ， 则 意味 着 既 不 能 让 当前 worker 进 程 频 索 地 试图 抢 
锁 ， 也 不 能 让 它 经 过 太 长 时 间 再 去 抢 锁 。 这 里 有 个 简单 的 判断 方法 ， 如 下 所 示 。 











if (timer == NGX TIMER INFINITE 
|| timer > ngx accept mutex delay) 











{ 


timer = ngx accept mutex delay; 





} 





这 意味 看 ， 即 使 开启 了 timer_resolution 时 间 精 度 ， 也 需要 让 ngx_process_events 方 法 在 没 
有 新 事件 的 时 候 至 少 等 等 ngx accept_mutex delay 写 秒 再 去 试图 抢 锁 。 而 没有 开启 时 间 精 度 
时 ， 如 果 最 近 一 个 定时 器 事件 的 超时 时 间距 离 现在 超过 了 ngx accept_mutex delay 坚 秒 的 话 ， 
也 要 把 timer 设 置 为 ngx accept mutex delay 毫秒 ， 这 是 因为 当前 进程 虽然 没有 抢 到 
accept_mutex 锁 ， 但 也 不 能 让 ngx process_events 方 法 在 没有 新 事件 的 时 候 等 待 的 时 间 超 过 


ngx_accept mutex_ delay 室 秒 ， 这 会 影响 整个 负载 均衡 机 制 。 














@ 注意。 nex_accept_mutex_delay 变 量 与 nginx.conf 配 置 文件 中 的 accept_mutex_delay 配 置 项 


的 参数 相关 内 容 可 参见 9.5 节 。 


7) 调用 ngx process_events 方 法 ， 并 计算 ngx process_events 执 行 时 消耗 的 时 间 ， 如 下 所 





delta = ngx current msec; 
(void) ngx process events(cycle, timer, flags); 
delta = ngx current msec - delta; 





其 中 ，delta 是 ngx_process_events 执 行 时 消耗 的 蝇 秒 数 ， 它 会 影响 第 10 步 中 触发 定时 器 的 


8) 如 果 ngx posted accept events 队 列 不 为 空 ， 那 么 调用 ngx_event process_posted 方 法 执 
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行 ngx_ posted_ accept events 队 列 中 需要 建立 新 连接 的 事件 。 


9) 如 果 ngx_accept mutex held 标志 位 为 1， 则 表示 当前 进程 获得 了 accept mutex 锁 ， 而 且 
在 第 8 步 中 也 已 经 处 理 完 了 新 连接 事件 ， 这 时 需要 调用 ngx_shmtx_unlock 释 放 accept_ mutex 锁 。 


10) 如 果 ngx_process_events 执 行 时 消耗 的 时 间 delta 大 于 0， 而 且 这 时 可 能 有 新 的 定时 器 
事件 被 触及 ， 那 么 需要 调用 ngx event expire timers 方 法 处 理 所 有 满足 条 件 的 定时 器 事件 。 


11) 如 果 ngx_posted_events 队 列 不 为 室 ， 则 调用 ngx_event_process_posted 方 法 执行 
ngx_posted_events 队 列 中 的 普通 读 / 写 事件 。 


Je 


至 此 ，ngx process_events_and timers 方 法 执行 完毕 。 注 意 ， 
ngx_process_events_and_timers 方 法 就 是 Nginx 实 际 上 处 理 Web 服 务 的 方法 ， 所 有 业务 的 执行 都 
是 由 它 开始 的 。ngx_process_events and timers 方 法 涉及 Nginx 完 整 的 事件 驱动 机 制 ， 因 此 ， 它 
也 把 之 前 介绍 的 内 容 整 合 在 一 起 了 ， 读 者 需要 格外 注意 。 
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9.9 文件 的 异步 IO 





本 章 之 前 提 到 的 事件 驱动 模块 都 是 在 处 理 网 络 事件 ， 而 没有 涉及 磁盘 上 文件 的 操作 。 本 
节 将 讨论 Linux 内 核 2.6.2x 之 后 版 本 中 文 持 的 文件 异步 JO， 以 及 ngx_epoll module 模 块 是 如 何 
与 文件 异步 WO 配合 提供 服务 的 。 这 里 提 到 的 文件 异步 WO 并 不 是 glibc 库 提供 的 文件 异步 /O。 
ibc 库 提供 的 异步 WO 是 基于 多 线程 实现 的 ， 它 不 是 真正 意义 上 的 异步 WO。 而 本 节 说 明 的 异 
步 JO 是 由 Linux 内 核实 现 ， 只 有 在 内 核 中 成 功 地 完成 了 磁盘 操作 ， 内 核 才 会 通知 进程 ， 进 而 
使 得 磁盘 文件 的 处 理 与 网 络 事件 的 处 理 同样 高 效 。 











使 用 这 种 方式 的 前 提 是 Linux 内 核 版 本 中 必须 支持 文件 腊 步 WO。 当 然 ， 它 带 来 的 好 处 也 
非常 明显 ，Nginx 把 读 取 文 件 的 操作 和 卉 步 地 提交 给 内 核 后 ， 内 核 会 通知 W/O 设 备 独立 地 执行 操 
作 ， 这 样 ，Nginx 进 程 可 以 继续 充分 地 占用 CPU。 而 且 ， 当 大 量 读 事件 堆积 到 IO 设备 的 队列 
中 时 ， 将 会 发 挥 出 内 核 中 “电梯 算法 ”的 优势 ， 从 而 降低 随机 读 取 磁盘 慎 区 的 成 本 。 





@ ,is Linux 内 核 级 别 的 文件 异步 1/ 〇 是 不 支持 缓存 操作 的 ， 也 就 是 说 ， 即 使 需要 操 

作 的 文件 块 在 Linux 文 件 缓存 中 存在 ， 也 不 会 通过 读 取 、 更 改 缓存 中 的 文件 块 来 代替 实际 对 

磁盘 的 操作 ， 虽 然 从 阻塞 wotker 进 程 的 角度 上 来 说 有 了 很 大 好 转 ， 但 是 对 单个 请 求 来 说 ， 还 

是 有 可 能 降低 实际 处 理 的 速度 ， 因 为 原先 可 以 从 内 存 中 快速 获取 的 文件 块 在 使 用 了 异步 I/O 

后 则 一 定 会 从 磁盘 上 读 取 。 异 步 文件 I/O 是 把 “ 双 刃 剑 ”， 关 键 要 看 使 用 场景 ， 如 果 大 部 分 

用 户 请 求 对 文件 的 操作 都 会 落 到 文件 缓存 中 ， 那 么 不 要 使 用 异步 LO， 反 之 则 可 以 试 着 使 用 
文件 异步 /JO ， 看 一 下 是 否 会 为 服务 带 来 并 发 能 力 上 的 提升 。 


目前 ，Nginx 仅 支持 在 读 取 文 件 时 使 用 异步 I/O ， 因 为 正常 写 入 文件 时 往往 是 写 入 内 存 中 


就 立刻 返回 ， 效 率 很 高 ， 而 使 用 异步 I/O 写 入 时 速度 会 明显 下 降 。 


9.9.1 _ Linux 内 核 提供 的 文件 异步 IO 
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Linux 内 核 提 供 了 5 个 系统 调用 完成 文件 操作 的 异步 JO 功 能 ， 见 表 9-7。 


表 9-7 Linux 内 核 提 供 的 文件 异步 1/O 〇 操作 方法 


方法 名 执行 意义 
初始 化 文件 异步 VO 的 上 下 文 ， 
nr_events 表示 需要 初始 化 的 异步 了 | 执行 成 功 后 rp 就 是 分 配 的 上 下 
O 上 下 文 可 以 处 理 的 事件 的 最 小 个 数 , | 文 描述 符 ， 这 个 异步 WO 上 下 文 
ctxp 是 文件 异步 IO 的 上 下 文 描 述 符 指针 | 将 至 少 可 以 处 理 mnr_events 个 事 
件 。 返回 0 表示 成 功 
销毁 文件 异步 WO 的 上 下 文 
返回 0 表示 成 功 


int io_setup(unsigned DT_events. 


alo_context t *ctxp) 


int io_destroy (aio_context t ctx) ctx 是 文件 异步 IO 的 上 下 文 描述 4 


ctx 是 文件 异步 IO 的 上 下 文 描 述 
nr 是 一 次 提交 的 事件 个 数 ，cbp 是 需 一 
是 交 的 事件 数组 中 的 首 个 元 素 地 址 

ctx 是 文件 异步 IO 的 上 下 文 描述 符 , | 取消 之 前 使 用 io_sumbit 提交 
iocb 是 要 取消 的 异步 VO 操作 ， 而 result | 的 一 个 文件 异步 WO 操作。 返回 
表示 这 个 操作 的 执行 结果 0 表示 成 功 

ctx 是 文件 异步 IO 的 上 下 文 描述 符 


是 交 文 件 异步 LO 操作。 返回 
值 表 示 成 功 提交 的 事件 个 数 


int 10_ submit(aio context t ctx, 


long nr, struct 10cb *cbp[]) 


it 10_cancel(alo context t ctx. struct 


iocb *locb, struct 10_event *result) 


min nr 表示 至 少 要 获取 min nr 个 事 件 ， 


int 10 getevents(aio context t ctx. re 个 事 人 
而 nr 表示 至 多 获 0 nr 个 事件 ， 它 与 


events 数组 的 个 数 一 般 是 相同 的 ; events 
是 执行 完成 的 事件 py timeout 是 超时 
时 间 ， 也 就 是 在 获取 min nr 个 事件 前 的 
等 待 时 间 


从 已 经 完成 的 文件 异步 I/O 操 
作 队 列 中 读 取 操作 


long min nr, long nr. 
struct 10 event *events, struct 


timespec *timeout) 





表 9-7 中 列举 的 这 5 种 方法 提供 了 内 核 级 别 的 文件 异步 WO 机 制 ， 使 用 前 需要 先 调用 
io_setup 方 法 初始 化 异步 WO 上 下 文 。 虽然 一 个 进程 可 以 拥有 多 个 异步 JO 上 下 文 ， 但 通常 有 一 
个 就 足够 了 。 调 用 io ee 个 异步 JO 上 下 文 的 描述 符 〈aio_context 类 型 )， 
这 个 描述 符 和 epoll_ create 返回 的 描述 符 一 样 ， 是 贯穿 始终 的 。 注 意 ，nr_events 只 是 指定 了 异 
步 JO 至 少 初始 化 的 上 下 文 容量 ， 它 并 没有 限制 最 大 可 以 处 理 的 异步 JO 事 件数 目 。 为 了 便于 
理解 ， 不 妨 将 io_setup 与 epoll_create 进 行 对 比 ， 它 们 还 是 很 相似 的 。 





既然 把 epoll 和 有 异步 IO 进行 对 比 ， 那 么 哪些 调用 相当 于 epoll ctrl 呢 ? 就 是 io_submit 和 
io_cancel。 其 中 io_submit 相 当 于 辐 噶 步 O 中 添加 事件 ， 而 io_cancel 则 相当 于 从 异步 JO 中 移 
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除 事件 。io_submit 中 用 到 了 一 个 结构 体 iocb， 下 面 简 单 地 看 一 下 它 的 定义 。 





er 


/* 存 储 着 业务 需要 的 指针 。 例 如 ， 在 


Nginx 中 ， 这 个 字段 通常 存储 着 对 应 的 


ngx event 事件 的 指针 。 它 实际 上 与 


io_getevents 方 法 中 返回 的 


io event 结 构 体 的 


data 成 员 一 致 的 


0 
他 
OY 
> 


*/ 


u int64 t aio data; 


// 不 需要 设置 





u int32 t PADDED (aio key，aio reserved1l); // 操作 码 ， 其 取 值 范围 是 


io iocb cmq 七 中 的 枚 举 命 令 
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u int1l16 七 aio lio opcode; 





// 请 求 的 优先 级 


int16 t aio reqprio; 


// 文件 描述 符 


nt32 t aio fildes:; 


// 读 


/ 写 操作 对 应 的 用 户 态 缓冲 区 


u_ int64 七 aio buf; 


// 读 


/ 写 操作 的 字 节 长 度 


u int64 t aio nbytes; 


// 读 
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/ 写 操作 对 应 于 文件 中 的 偏 移 量 


int64 t aio offset; 


// 保留 字段 


u int64 七 aio reserved2; 


/* 表 示 可 以 设置 为 


IOCB_FLAG_RESFD， 它 会 告诉 内 核 当 有 异步 





I/O 请 求 处 理 完 成 时 使 用 
eventfd 进 行 通知 ， 可 与 
epoll 配 合 使 用 ， 其 在 
Nginx 中 的 使 用 方法 可 参见 


9.9.2 节 


TT 人 人 人 人 位 人们 Ve 





nt32 七 aio flags; 


// 表示 当 使 用 





IOCB_FLAG_RESFD 标 志 位 时 ， 用 于 进行 事件 通知 的 句柄 


u int32 t aio resfd; 





因此 ， 在 设置 好 iocb 结 构 体 后 ， 就 可 以 向 异步 JO 提 交 事 件 了 。aio_lio_opcode 操 作 码 指 
定 了 这 个 事件 的 操作 类 型 ， 它 的 取 值 范围 如 下 。 





typedef enum io iocb cmd { 


// 异步 读 操作 


IO CMD PREAD = 0, 





// 异步 写 操作 


IO CMD PWRITE = 1, 





// 强制 同步 
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// 目前 未 使 用 


IO CMD FDSYNC = 3, 


// 目前 未 使 用 


IO CMD POLL = 5, 


// 不 做 任何 事情 


IO_CMD NOOP = 6， 


1Gcb ema 二 





在 Nginx 中 ， 仪 使 用 了 IO_CMD_PREAD 命 令 ， 这 是 因为 目前 仅 支 持 文件 的 寞 步 WO 读 取 ， 
不 支持 异步 WO 的 写 入 。 这 其 中 一 个 重要 的 原因 是 文件 的 异步 WO 无 法 利用 缓存 ， 而 写 文 件 操 
作 通 第 是 落 到 绥 存 中 的 ，Linux 存 在 统一 将 缓存 中 “ 脏 ” 数 据 刷新 到 磁盘 的 机 制 。 





这 样 ， 使 用 io_submit 向 内 核 提 交 了 文件 异步 JO 操 作 的 事件 后 ， 再 使 用 io_cancel 则 可 以 将 
己 经 提交 的 事件 取消 。 


如 何 获 取 已 经 完成 的 异步 JO 事 件 呢 ? io_getevents 方 法 可 以 做 到 ， 它 相当 于 epoll 中 的 
epoll wait 方 法。 这 里 用 到 了 io_event 结 构 体 ， 下 面 看 一 下 它 的 定义 。 


struct io event { 


全 六 全 nnnnn http://ww linuxorobe. con 





iocb 结 构 体 中 的 


aio data 是 一 致 的 


uint64 t data; 





// 指向 提交 事件 时 对 应 的 


iocb 结 构 体 


uint64 t obj; 


// 异步 


I/O 请 求 的 结构 。 


res 大 于 或 等 于 


0 时 表示 成 功 ， 小 于 


0 时 表示 失败 
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int64 七 res; 


// 保留 字段 


int64 t res2; 


这 样 ， 根 据 获 取 的 io_event 结 构 体 数组 ， 束 可 以 获得 已 经 完成 的 异步 LO 操作 了， 特别 是 
iocb 结 构 体 中 的 aio_data 成 员 和 io_event 中 的 data， 可 用 于 传递 指针 ， 也 就 是 说 ， 业 务 中 的 数 
据 结 构 、 事 件 完成 后 的 回调 方法 都 在 这 里 。 


进程 退出 时 需要 调用 io_destroy 方 法 销毁 异步 JO 上 和 下文， 这 相当 于 调用 close 关 闭 epoll 的 


描述 符 。 


Linux 内 核 提 供 的 文件 异步 7O 机 制 用 法 非常 简单 ， 它 充分 利用 了 在 内 核 中 CPU 与 IO 设备 
古 各 自 独 立 工作 的 这 一 特性 ， 在 提交 了 寞 步 WO 操 作 后 ， 进 程 完全 可 以 做 其 他 工作 ， 直 到 空 
内 再 来 查看 异步 WO 操作 是 否 完 成 。 


9.9.2 ngx_epoll module 模 块 中 实现 的 针对 文件 的 异步 /O 


在 Nginx 中 ， 文 件 异步 WO 事件 完成 后 的 通知 是 集成 到 epoll 中 的 ， 它 是 通过 9.9.1 节 中 介绍 
的 IOCB FLAG RESFD 标 志 位 完成 的 。 下 面 看 看 文件 异步 1O 事 件 在 ngx epoll module 模 块 中 
是 如 何 实 现 的 ， 其 中 在 文件 异步 VO 机 制 中 定义 的 全 局 变量 如 下 。 


// 用 于 通知 异步 
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TI/O 事 件 的 描述 符 ， 它 与 


iocb 结 构 体 中 的 


aio resfd 成 员 是 一 致 的 


irnt rngx eventfd = =1; 


// 异步 


I/O 的 上 下 文 ， 全 局 唯一 ， 必 须 经 过 


io_setup 初 始 化 才能 使 用 


aio context t ngx aio ctx = 0; 


/* 异 步 


I/O 事 件 完成 后 进行 通知 的 描述 符 ， 也 就 是 


ngx_eventfd 所 对 应 的 
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ngx event t 事件 


*/ 
static ngx event t ngx eventfqd event; /* 异 步 
I/O 事 件 完 成 后 进行 通知 的 描述 符 
ngx_eventfd 所 对 应 的 
ngx connection 七 连接 
*/ 


static ngx connection t ngx eventfd conn; 





在 9.6.3 节 的 ngx epoll init 代 码 中 ， 在 epoll_create 执 行 完 成 后 如 果 开 启 了 文件 异步 /O 功 
能 ， 则 会 调用 ngx_epoll aio init 方 法 。 现 在 详细 摘 述 一 下 ngx_epoll aio init 方 法 中 做 了 些 什 
从 ; 如 下 所 不 





#define SYS eventfd 323 


static void ngx epoll aio init(ngx cycle t *cycle, ngx epoll conf t *epcf) { 


了 和 七 注 池 





struct epoll event 


// 使 用 


Linu 
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323 个 系统 调用 获取 一 个 描述 符 句柄 


ngx eventfd = Syscal1Ll(SYS_ eventfd, 0); … 


// 设置 


ngx_ eventfd 为 无 阻塞 


if (ioctl (ngx eventfd, FIONBIO, &n) == -1) { 


// 初始 化 文件 异步 


I7NO 的 .二 下 文 


if (io_setup (epcf->aio requests, &ngx aio ctx) == -1) { 


} 
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/* 设 置 用 于 异步 


I/O 完 成 通知 的 


ngx eventfd _ event 事 件 ， 它 与 


ngx eventfd conn 连 接 是 对 应 的 


*/ 


ngx eventfqd event.data = &ngx eventfqd conn; // 在 异步 


I/O 事 件 完成 后 ， 使 用 


ngx_ epoll eventfqd handler 方 法 处 理 





ngx eventfd event.handler = ngx epoll eventfd handler; ngx eventfd event.l1og = cycle->log; ngx eventfd event 


ngx_ eventfd conn 连 接 


ngx eventfdqd conn.fd = ngx eventfd; // ngx eventfqd conn 连 接 的 读 事件 就 是 上 面 的 


ngx_ eventfd event 
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ngx eventfd conn.read = &ngx eventfd event ngx eventfd conn.1log = Cycle->1log ee.events = EPOLLIN|EPOLLET; 





ee.data.ptr = &ngx eventfd conn; // 向 


epoll 中 添加 到 异步 


I/0 的 通知 描述 符 


ngx eventfd 





if (epoll ctl (ep, EPOLL CTL ADD, ngx eventfd, &ee) != -1) { 


return; 





这 样 ，ngx epoll aio init 方 法 会 把 异步 /0O 与 epoll 结 合 起 来 ， 当 某 一 个 异步 /O 事 件 完成 
后 ，ngx_eventfd 句 柄 就 处 于 可 用 状态 ， 这 样 epoll wait 人 在 返回 ngx eventfd event 事 件 后 就 会 调 
用 它 的 回调 方法 ngx epoll eventfd handler 处 理 已 经 完成 的 异步 IO 事件 ， 下 面 看 一 下 
ngx epoll eventfd_handler 方 法 主要 在 做 些 什 么 ， 代 人 码 如 下 所 示 。 








static void ngx epoll eventfd handler (ngx event t *ev) { 
int n, events; 


uint64 t ready; 
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64 个 事件 





struct io event event[64]; 
struct timespec ts; 


/* 获 取 已 经 完成 的 事件 数目 ， 并 设置 到 


ready 中 ,注意 ， 这 个 


ready 是 可 以 大 于 


64 的 
4 


n= read(ngx eventfd, &ready, 8); … 


// ready 表 示 还 未 处 理 的 事件 。 当 


ready 大 于 
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0 时 继续 处 理 


while (ready) { 


// 调用 


io_getevents 获 取 已 经 完成 的 异步 


I/O 事 件 





vents = io getevents (ngxX aio ctx, 1, 64, event, &ts); if (events > 0) { 


// 


某 


ready 减 去 已 经 取出 的 事件 


ready -= events; 


// 处 理 





event 数 组 里 的 事 


个 


件 
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// data 成 员 指 向 这 个 异步 


I/O 事 件 对 应 着 的 实际 事件 


e = (ngx event 七 *) (uintptr t) event[i].data; 





// 将 该 事件 放 到 


ngx _ posted events 队 列 中 延 后 执行 


ngx post event(e, &ngx posted events); } 


continue; 


if (events == 0) { 


return; 


return; 








整个 网 络 事件 的 驱动 机 制 就 是 这 样 通过 ngx_eventfd 通 知 描述 符 和 
ngx_epoll_eventfd_ handler 回 调 方法 ， 并 与 文件 异步 /O 事 件 结 合 起 来 的 。 


8 么 ， 怎 样 癌 异步 JO 上 下 文中 提交 异步 IO 操作 呢 ? 看 看 ngx_ linux aio read.c 文 件 中 的 
ngx_file aio_read 方 法 ， 在 打开 文件 异步 JO 后 ， 这 个 方法 将 会 负责 磁盘 文件 的 读 取 ， 如 下 所 


小 。 





ssize t ngx file aio read(ngx file t file, u char buf, size t size, off t offset, ngx pool 七 *pool) { 





ngx err 七 err; 
struct iocb *pDLOCGD [LL] > 
ngx event t *ev; 


ngx event aio t *aio; 


aio = file->aio; 


ev = &aio->event; 


ngx memzero (&aio->aiocb, sizeof (struct iocb)); /* 设 置 
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iocb 结 构 体 ， 这 里 的 


aiocb 成 员 就 是 


iocb 类 型 。 注 意 ， 


aio_qdata 已 经 设置 为 这 个 


ngx_event 鞋 事件 的 指针 ， 这 样 ， 从 


io_getevents 方 法 获取 的 


io_event 对 象 中 的 


data 也 是 这 个 指针 


4 





aio->aiocb.aio data = (uint64 t) (uintptr t) ev; aio->aiocb.aio lio opcode = IOCB CMD PREAD; aio->aiocb.aio 


ngx file aio event handler，, 它 的 调用 关系 类 似 这 样 





:epoll wait 中 调用 
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ngx_epol1_eventfq handler 方法 将 当前 事件 放 入 到 


ngx_posted events 队 列 中 ， 在 延 后 执行 的 队列 中 调用 


ngx file aio event handler 方 法 





wy 


ev->handler = ngx file aio event handler; piocb[0] = &aio->aiocb; /* 调 用 





io submit 向 


ngx_aio ctx 和 异步 


I/O 上 下 文中 添加 


1 个 事件 ， 返 回 





1 表示 成 功 
二 
if (io submit (ngx aio ctx, 1, piocb) == 1) { 


ev->active = 


[| TH 中 站 由 II http://wWw |1 nuxorobe. con 





ev->ready = 0; 


ev->complete = 0; 


return NGX AGAIN; 





下 面 看 一 下 ngx event aio t 结 构 体 的 定义 。 





typedef struct ngx event aio s ngx event aio t; struct ngx event aio s { 


void *data; 


// 这 是 真正 由 业务 模块 实现 的 方法 ， 在 异步 


I/O 事 件 完 成 后 被 调用 


ngx event handler pt handler; ngx file 七 *file; 


ngx fd 七 fd; 





#if (NGX HAVE EVENTFD) 














int64 t res; 
#else 


ngx err t err 
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size 七 nbytes; 


#endif 





#if (NGX HAVE AIO SENDFILE 














off t last offset; 


#endif 


// 这 里 的 


ngx aiocb 就 是 


9.9.1 节 中 介绍 的 


iocb 结 构 体 


ngx aiocb 七 aiocb; 


ngx event t event; 





这 样 ，ngx file aio read 方法 会 问 异 步 JO 上 下 文中 添加 事件 ， 该 epoll _ wait 在 通过 
ngx_eventfd 摘 述 符 检 测 到 异步 IO 事件 后 ， 会 再 调用 ngx_epoll_eventfd_ handler 方 法 将 io_event 
事件 取出 来 ， 放 入 ngx_posted_events 队 列 中 延 后 执行 。ngx_posted_events 队 列 中 的 事件 执行 
时 ， 则 会 调用 ngx file aio event handler 方 法 。 下 面 看 一 下 ngx file aio event handler 方 法 做 了 
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些 什么 ， 代 码 如 下 所 示 。 





static void ngx file aio event handler (ngx event t *ev) { 








ngx event aio t *aio; 


aio = ev->data; 


aio->handler (ev); 





这 里 调用 了 ngx event aio t 结 构 体 的 handler 回 调 方 法 ， 这 个 回调 方法 是 由 真正 的 业务 模 
块 实现 的 ， 也 惑 是 说 ， 任 一 个 业务 模块 想 使 用 文件 异步 J0， 就 可 以 实现 handler 方 法 ， 这 
样 ， 在 文件 异步 操作 完成 后 ， 该 方法 就 会 被 回调 。 
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9.10 ITCP 协 议 与 Nginx 
作为 Web 服 务 器 的 nginx， 主 要 任务 当然 是 处 理 好 基于 TCP 的 HTTP 协 议 ， 本 节 将 深入 TCP 
协议 的 实现 细节 (linux 下) 以 更 好 地 理解 Nginx 事 件 处 理 机 制 。 


TCP 和 旦 一 个 面 问 连接 的 协议 ， 它 必须 基于 建立 好 的 TCP 连 接 来 为 通信 的 两 方 提 供 可 靠 的 
字 贡 流 服 务 。 建 YTCP 连 接 是 我 们 耳熟能详 的 三 次 握手 : 


1) 客户 端 同 服务 器 发 起 连接 (SYN) 。 
2) 服务 器 确认 收 到 并 向 客户 端 也 发 起 连接 (ACK+SYN) 。 
3) 客户 端 确认 收 到 服务 器 发 起 的 连接 (ACK) 。 


这 个 建立 连接 的 过 程 是 在 操作 系统 内 核 中 完成 的 ， 而 如 Nginx 这 样 的 应 用 程序 只 是 从 内 
核 中 取出 已 经 建立 好 的 TCP 连 接 。 大 多 时 候 ，Nginx 是 作为 连接 的 服务 器 方 存在 的 ， 我 们 看 一 
看 Linux 内 核 是 怎样 处 理 TCP 连 接 建 立 的 ， 如 图 9-8 所 示 。 
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1.2 插 入 队列 
2.2 由 队列 中 取出 


2.3 插 入 队列 


accept 取 出 连接 套 接 字 





3 调 | 


图 9-8 ”服务 器 端 建立 TCP 连 接 的 简化 示意 图 


图 9-8 中 简单 地 表达 了 一 个 观点 : 内 核 在 我 们 调用 listen 方 法 时 ， 就 已 经 为 这 个 监听 端口 
建立 了 SYN 队 列 和 ACCEPT 队 列 ， 当 客户 端 使 用 connect 方 法 向 服务 器 发 起 TCP 连 接 ， 随 后 图 
中 1.1 步 又 客户 端的 SYN 包 到 达 了 服务 器 后 ， 内 核 会 把 这 一 信息 放 到 SYN 队 列 《 即 未 完成 握手 
队列 ) 中 ， 同 时 回 一 个 SYN+ACK 包 给 客户 端 。2.1 步 又 中 客户 端 再 次 发 来 了 针对 服务 器 SYN 
包 的 ACK 网 络 分 组 时 ， 内 核 会 把 连接 从 SYN 队 列 中 取出 ， 再 把 这 个 连接 放 到 ACCEPT 队 列 
( 即 已 完成 握手 队列 〉 中。 而 服务 器 在 第 3 步调 用 accept 方 法 建立 连接 时 ， 其 实 就 是 直接 从 
ACCEPT 队 列 中 取出 已 经 建 好 的 连接 而 已 。 
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这 样 ， 如 果 大 量 连接 同时 到 来 ， 而 应 用 程序 不 能 及 时 地 调用 accept 方 法 ， 就 会 导致 以 上 
两 个 队列 满 (ACCEPT 队 列 满 ， 进 而 也 会 导致 SYN 队 列 满 ) ， 从 而 导致 连接 无 法 建立 。 这 其 
实 很 常见 ， 比 如 Nginx 的 每 个 worker 进 程 都 负责 调用 accept 方 法 ， 如 果 一 个 Nginx 模 块 在 处 理 请 
求 时 长 时 间 陷入 了 某 个 方法 的 执行 中 (如 执行 计算 或 者 等 待 IO，， 就 有 可 能 导致 新 连接 无 法 
建立 。 





建立 好 连接 后 ，TCP 提 供 了 可 靠 的 字 节 流 服 务 。 怎 么 理解 所 谓 的 "可靠 ” 呢 ? 可 以 简单 概 
括 为 以 下 4 所 : 


1) TCP 的 send 方 法 可 以 发 送 任意 大 的 长 度 ， 但 数据 链 路 层 不 会 允许 一 个 报 文 太 大 的 ， 当 
报 文 长度 超 过 MTU 大 小 时 ， 它 一 定 会 把 超大 的 报 文 切 成 小 报 文 。 这 样 的 场景 是 不 被 TCP 接 受 
的 ， 切 分 报 文 段 既 然 不 可 避免 ， 那么 就 只 能 发 生 在 TCP 协 议 内 部 ， 这 才 是 最 有 效率 的 。 








2) 每 一 个 报 文 在 发 出 后 都 必须 收 到 “回执 ”一 ACK， 确保 对 方 收 到 ， 否 则 会 在 超时 时 
间 达 到 后 重 发 。 相 对 的 ， 接 收 到 一 个 报 文 时 也 必须 发 送 一 个 ACK 告 诉 对 方 。 


3) 报 文 在 网 络 中 传输 时 会 失 序 ，TCP 接 收 端 需要 重新 排序 失 序 的 报 文 ， 组 合成 友 送 时 
的 原 序 再 给 到 应 用 程序 。 当 然 ， 重复 的 报 文 也 要 丢弃 


4) 当 连 接 的 两 端 处 理 速度 不 一 至 时， 为 防止 TCP 缓 冲 区 溢出 ， 还 要 有 个 流量 控制 ， 减 
绥 速 度 更 快 一 方 的 发 送 速度 。 


从 以 上 4 后 可 以 看 到 ， 内 核 为 每 一 个 TCP 连 接 部 分 配 了 内 存 分 别 充 当 发 送 、 接 收 缓冲 
这 与 Nginx 这 种 应 用 程序 中 的 用 户 态 缓存 不 同 。 搞 清楚 内 核 的 TCP 读 写 缓存 区 ， 对 于 我 们 
判断 Nginx 的 处 理 能 力 很 有 帮助 ， 毕 竞 无 论 内 核 还 是 应 用 程序 都 在 抢 物 理 内 存 。 


先 来 看 看 调用 send 这 样 的 方法 用 送 TCP 字 节 流 时 ， 内 核 到 确 做 了 哪些 事 。 图 9-9 是 一 个 简 
单 的 send 方 法 调用 时 的 流程 示意 图 。 


i 外 Rr 








TCP 层 把 它 叫 做 MSS 最 大 报 文 段 长 度 〈 当 然 ，MSS 是 可 变 的 ) 。 在 图 9-9 的 场景 中 ， 假 定 待 发 
送 的 内 存 将 按照 MSS 被 切 分 为 3 个 报 文 ， 应 用 程序 在 第 1 步调 用 send 方 法 、 第 10 步 send 方 法 返 
回 之 间 ， 内 核 的 主要 任务 是 把 用 户 态 的 内 存 内 容 拷贝 到 内 核 态 的 TCP 缓 冲 区 上 ， 在 第 5$ 步 时 

假定 内 核 缓 存 区 暂时 不 足 ， 在 超时 时 间 内 又 等 到 了 足够 的 空 亲 空间 。 从 岁 中 可 以 看 到 ，send 
方法 成 功 返 回 并 不 等 于 就 把 报 文 发 送出 去 了 《当然 更 不 等 于 对 方 接收 到 了 报 文 ) 。 
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服务 天 
Linux 内 核 


wme, ae 
取出 MSS 分 组 发 送 
循环 地 将 待 发 送 字 符 
流 分 成 MSS 分 组 拷贝 
到 内 核 态 ee 
10 ) 全 部 或 者 部 分 发 送 
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8 ) tcp_push 


按 Nagle、 慢 启动 等 算法 发 送 报 文 





send 方 法 执行 时 的 流程 示意 图 





图 9-9 
当 调 用 recv 这 样 的 方法 接收 报 文 时 ，Nginx 是 基于 事件 驱动 的 ， 也 就 是 说 只 有 epoll 通 知 


worker 进 程 收 到 了 网 络 报 文 ，recv 才 会 被 调用 〈socket 也 被 设 为 非 阻 塞 模式 ) 。 图 9-10 就 是 一 


个 这 样 的 场景 ， 在 第 1~4 步 表示 接收 到 了 无 序 的 报 文 后 ， 内 核 是 怎样 重新 排序 的 。 第 5 步 开 
台 ， 应 用 程序 调用 了 recv 方 法 ， 内 核 开 始 把 TCP 读 缓冲 区 的 内 容 拷贝 到 应 用 程序 的 用 户 态 内 








存 中 ， 第 13 步 recv 方 法 返回 拷贝 的 字 节 数 。 图 中 用 到 了 linux 内 核 中 为 TCP 准 备 的 2 个 队列 : 
收 到 的 TGP 报 文 ， 去 除了 TCP 头 部 、 
| NUXIr ODE.,. CON 


oe 得 证 让 人 > 证 Fe 


WAWN 











排 好 序 放 入 的 、 用 户 进 程 可 以 直接 按 序 读 取 的 队列 ;out_of order 队 列 存放 乱 序 的 报 文 。 





回 过 头 来 看 ，Nginx 使 用 好 TCP 协 议 主 要 在 于 如 何 有 效率 地 使 用 CPU 和 内 存 。 只 在 必要 时 
才 调 用 TCP 的 send/recv 方 法 ， 这 样 就 避免 了 无 请 的 CPU 浪 费 。 例 如 ， 只 有 接收 到 报 文 ， 甚 至 
只 有 接收 到 足够 多 的 报 文 《SO_RCVLOWAT 阅 值 ) ，worker 进 程 才 有 可 能 调用 recv 方 法 。 同 
样 ， 只 在 发 送 缓冲 区 有 空闲 空间 时 才 去 调用 send 方 法 。 这 样 的 调用 才 是 有 效率 的 。Nginx 对 内 
存 的 分 配 是 很 节俭 的 ， 但 Linux 内 核 使 用 的 内 存 又 如 何 控制 呢 ? 





NNn httpo://ww linuxorobe. con 








服务 器 




















”默认 接收 国 值 为 1 
1 进程 分 配 了 
4 ) 遍历 out_of_order 取 出 S3-S4 放 入 receive 队 列 len 长 度 内 存 
和 / 
) 复制 到 用 户 太一 
队列 | py 
1 ) 搜 反 报 文 51-S2 插 入 receive 失 列 刘 复制 到 用 户 态 
Pa 
| 10 ) 复制 到 用 户 态 
队列 权 





3 ) 近 收 报 文 S2-S3 插 入 receive 队 列 


本 


cl 





11 ) 返回 







7 ) 处 理 receive 队 列 中 已 排序 的 报 文 5 ) 调用 recv 接 收 阻塞 socket 
锁 住 Socket， 获 取 





一 一 和 一 一 最 低 接收 阅 什 : 
含 查 是 否 | = pop 

加 涪 屋 代 硬 信 交 四 13 ) recv 方 法 返回 已 经 拷贝 的 S4-S1 字 节 数 
TCP 消 息 长 度 6 ) tcp_recvmsg 2 





12 ) 已 经 找 贝 的 字 节 数 超过 最 低 接收 阔 值 ， 
而 且 backlog 队 列 为 空 
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图 9-10 tecv 方 法 执行 时 的 流程 示意 图 


首先 ， 我 们 可 以 控制 内 存 缓存 的 上 限 ， 例 如 基于 setsockopt 方 法 实现 的 SO_SNDBUF、 
SO RCVBUF (Nginx 的 listen 配 置 里 的 sndbuf 和 rcvbuf 也 是 在 改 它 们 ， 参 见 2.4.1 节 ) 。 
SO_SNDBUF 表 示 这 个 连接 上 的 内 核 写 缓存 上 限 〈 事 实 上 SO_SNDBUF 也 并 不 是 精确 的 上 限 ， 
在 内 核 中 会 把 这 个 值 翻 一 倍 再 作为 写 缓存 上 限 使 用 ) 。 它 受制 于 系统 级 配置 的 上 下 限 
net.core.wmem max (参见 1.3.4 节 ) 。SO_RCVBUF 同 理 。 读 写 缓存 的 实际 内 存 大 小 与 场景 
关 。 对 读 缓存 来 说 ， 接 收 到 一 个 来 自 连 接 对 端的 TCP 报 文 时 ， 会 导致 读 缓 存 增加 ， 如 果 超过 
了 读 缓存 上 限 ， 那 么 这 个 报 文 会 被 丢弃 。 当 进程 调用 read、recv 这 样 的 方法 读 取 字 节 流 时 ， 
读 缓 存 就 会 减少 。 因 此 ， 读 缓存 是 一 个 动态 变化 的 、 实 际 用 到 多 少 才 分 配 多 少 的 缓冲 内 存 。 


用 全 | 人 时 ， HE . A | a a 全 EE 己 经 











到 达 上 限 ， 那 么 写 缓存 维持 不 变 ， 向 用 户 进程 返回 失败 。 而 每 当 接 收 到 连接 对 端 发 来 的 
ACK， 确 认 了 报 文 的 成 功 发 送 时 ， 写 缓存 就 会 减少 。 可 见 缓 存 上 限 所 起 作用 为 :丢弃 新 报 
文 ， 防止 这 个 TCP 连 接 消 耗 太 多 的 内 存 。 





其 次 ， 我 们 可 以 使 用 Linux 提 供 的 自动 内 存 调整 功能 


net.ipv4.tcp moderate rcvbuf = 1 


默认 tcp_moderate_revbuf 配 置 为 !， 表 示 打 开 了 TCP 内 存 自动 调整 功能 。 奉 配置 为 0， 这 
个 功能 将 不 会 生效 〈 慎 用 ) 。 


@ i 当 我 们 在 编程 中 对 连接 设置 了 SO_SNDBUF、SO_RCVBUF， 将 会 使 Linux 内 
核 不 再 对 这 样 的 连接 执行 自动 调整 功能 ! 


那么 ， 这 个 功能 到 底 是 怎样 起 作用 的 呢 ? 举 个 例子 ， 请 看 下 面 的 绥 存 上 限 配置 : 


net.ipv4.tcp rmem = 8192 87380 16777216 
net.ipv4.tcp wmem = 8192 65536 16777216 
net.ipv4.tcp mem = 8388608 12582912 16777216 


tcp_rmem[3] 数 组 表示 任何 一 个 TCP 连 接 上 的 读 缓存 上 限 ， 其 中 tcp_rmem[0] 表 示 最 小 上 
限 ，tcp_rmem[1] 表 示 初 始 上 限 “〈 注 意 ， 它 会 履 盖 适用 于 所 有 协议 的 rmem default 配 置 )， 
tcp_rmem[2] 表 示 最 大 上 限 。tcp wmem[3] 数 组 表示 写 缓存 ， 与 tcp_rmem[3] 类 似 。 


tcp_mem[3] 数 组 就 用 来 设 定 TCP 内 存 的 整体 使 用 状况 ， 所 以 它 的 值 很 大 〈 它 的 单位 也 不 
是 字 节 ， 而 是 页 一 一 4KB 或 者 8SKB 等 这 样 的 单位 ! ) 。 这 3 个 值 定 义 了 TCP 整 体内 存 的 无 压力 
值 、 压 力 模 式 开局 国 值 、 最 大 使 用 值 。 以 这 3 个 值 为 标记 点 则 内 存 共 有 4 种 情况 《如 图 9-11 所 


不 ): 


1) 当 TCP 整 体内 存 小 于 tcp_mem[0] 时 ， 表 示 系 统 内 存 总 体 无 压力 。 知 之 前 内 存 曾 经 超过 
了 tcp_mem[l] 使 系统 进入 内 存 压力 模式 ， 那 么 此 时 也 会 把 压力 模式 关闭 。 此 时 ， 只 要 TCP 连 
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接 使 用 的 缓存 没有 达到 上 限 ， 那 么 新 内 存 的 分 配 一 定 是 成 功 的 。 


2) 当 TCP 内 存在 trp_ mem[0] 与 ttp mem[l] 之 间 时 ， 系 统 可 能 处 于 内 存 压 力 模式 ， 例 如 总 
内 存 刚 从 tcp mem[1] 之 上 下 来 ; 也 可 能 是 在 非 压 力 模式 下 ， 例 如 总 内 存 刚 从 tcp_mem[0] 以 下 
十 来。 








此 时 ， 无 论 是 否 在 压力 模式 下 ， 只 要 TCP 连 接 所 用 缓存 未 超过 tcp_rmem[0] 或 者 
tcp_wmem[0]， 那 么 都 一 定 能 成 功 分 配 新 内 存 。 人 否则 ， 基 本 上 惑 会 面临 分 配 失败 的 状况 。 
(还 有 少量 例外 场景 允许 分 配 内 存 成 功 ， 这 里 不 纠结 内 核 的 实现 细节 ， 故 略 过 。) 


3) 当 TCP 内 存在 tcp_mem[1] 与 ttp_mem[2] 之 间 时 ， 系 统一 定 处 于 系统 压力 模式 下 。 行 为 
与 情况 2 相同 。 


4) 当 TCP 内 存在 tcp_mem[2] 之 上 时 ， 所 有 的 新 TCP 绥 存 分 配 都 会 失败 。 
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连接 已 用 缓存 是 否 超过 缓存 上 限 ? 


[未 超过 ] 


TCP 总 内 存 是 否 小 于 tcp_mem[0]? 





[不 小 于 ] 


™ 


过 tcp_rmem[0| 或 者 tcp_wmem[0]? 


分 配 缓存 成 功 分 配 缓存 失败 


DO http' /ww inuxorobe, con 





图 9-11 Linux 下 TCP 缓 存 上 限 的 自 适应 调整 
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9.11 小 结 


本 间 在 具体 的 事件 驱动 模块 基础 上 以 epoll 方 式 为 例 ， 完 整地 阐述 了 Nginx 的 事件 驱动 机 
制 ， 并 介绍 了 3 个 与 事件 驱动 密切 相关 的 Nginx 模 块 ， 同 时 说 明了 事件 驱动 中 的 流程 是 如 何 执 
行 的 。 刀 外 ， 还 介绍 了 Nginx 在 高 并 发 服务 需 设 计 上 的 一 些 扩 巧 ， 这 不 仅 对 我 们 了 解 Nginx 的 
架构 有 所 帮助 ， 更 对 我 们 以 后 设计 独立 的 高 性 能 服务 器 有 非常 大 的 局 发 意义 。 本 章 内 容 也 是 
Nginx 其 他 模块 的 基础 ， 之 后 的 章节 都 是 在 讨论 事件 消费 模块 ， 特 别 是 后 续 的 HTTP 模块 ， 在 
学 习 它 们 的 设计 方法 时 我 们 会 经 党 性 地 返回 到 本 章 的 事件 驱动 机 制 中 。 
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第 10 章 HTTP 框架 的 初始 化 


从 本 章 开始 将 探讨 事件 消费 模块 的 “< 大户” 一 一 HTTP 模 块 。Nginx 作 为 Web 服 务 绅 ， 其 
HTTP 模 块 的 数量 远 超过 了 其 他 4 类 模块 (核心 模块 、 事 件 模块 、 配 置 模块 、 邮 件 模 块 ) ， 其 
代码 规模 也 同样 遥遥 领先 。 


这 些 实现 了 丰富 多 样 功能 的 HITP 模 块 是 以 一 种 什么 样 的 方式 组 织 起 来 的 呢 ? 它们 各 目 
功能 的 高 度 可 定制 性 是 如 何 实现 的 ? 共性 在 哪里 ? Nginx 又 是 怎样 把 这 些 共 性 的 内 容 提 取出 
来 ， 并 以 一 个 强大 的 HTTP 框 架 帮 助 各 个 HTTP 模 块 实现 具体 的 功能 呢 ? 


在 回答 这 些 问题 前 ， 先 来 回顾 一 下 本 书 的 第 二 部 分 ， 因 为 第 二 部 分 始终 在 讲 如 何 开发 一 
个 HTTP 模 块 ， 这 种 应 用 级 别 的 HTTP 模 块 就 是 由 HTTP 框 架 定义 和 管理 的 。HTTP 框 架 大 致 由 
1 个 核心 模块 (ngx_http_module〉、 两 个 HTTP 模 块 (ngx_http_core_module、 
ngx_http_upstream_module〉 组 成 ， 它 将 负 员 调度 其 他 HTTP 模 块 来 一 起 处 理 用 户 请 求 。 下 面 
先 来 弄 清楚 普通 的 HTTP 模 块 和 HTTP 框 架 各 自 的 关注 点 在 哪里 。 





先 来 看 第 3 章 ~ 第 5 半 例 子 中 的 HTTP 模 块 通常 会 做 哪些 工作 : 





1) 处 理 已 经 解析 完毕 的 HTTP 请 求 〈( 也 就 是 第 二 部 分 中 反复 提 到 的 填充 好 的 
ngx http request t 结 构 体 ) 。 





2) 获取 到 nginx.conf 里 自己 感 兴趣 的 配置 项 ， 无 论 它 们 是 否 同 时 出 现在 不 同 的 http 全 配置 
块 、server{} 配 置 块 或 者 location{} 配置 块 下 ， 都 需要 正确 地 解析 出 ， 以 此 决定 针对 不 同 的 用 
户 请 求 定制 不 同 的 功能 


3) 调用 HITP 框 架 提 供 的 方法 就 可 以 发 送 HTTP 响 应 ， 包 括 使 用 磁盘 IO 读 取 数 据 并 发 


Oe 





理 。 例 如 ，nsgx_http_access module 模 块根 据 卫 信息 拒绝 一 个 用 户 请 求 后 ， 本 应 接着 执行 的 其 
他 HTTP 模 块 将 没有 机 会 再 处 理 这 个 请 求 。 


5) 异步 接收 HTTP 请求 中 的 包 体 ， 可 以 将 网 络 数据 保存 到 磁盘 上 。 
6) 异步 访问 第 三 方 服 务 。 


7) 分 解 出 多 个 子 请 求 来 构造 处 理 复杂 业务 的 能 力 ， 子 请 求 间 的 处 理 仍 然 是 异步 化 、 非 





以 上 只 是 一 个 简单 粗略 的 总 结 ，HITP 模 块 或 多 或 少 都 会 需要 这 些 功能 。 以 这 些 功能 大 


例 ， 我 们 来 探讨 一 下 HTTP 框 架 人 至少 要 完成 哪些 基础 性 的 工作 。 





1) 处理 所 有 http 介 块 内 的 配置 项 ， 管 理 每 个 HTTP 模 块 感 兴趣 的 配置 项 (允许 同一 个 
http{} 下 出 现 多 个 server{}、location 人 等 子 配 置 块 ， 人 允许 同名 的 配置 项 同时 出 现在 各 种 配置 块 
中 ) 。 








2) HITP 框 架 要 能 够 使 用 第 9 章 介 绍 的 事件 模块 监听 Web 端 口 ， 并 处 理 新 连接 事件 、 可 
读 事件 、 可 写 事件 等 。 





3) HTITP 框 架 需 要 有 状态 机 来 分 析 接 收 到 的 TCP 字 符 流 是 否 是 完整 的 HITP 包 。 


4) HTTP 框架 能 够 根据 接收 到 的 HITP 请 求 中 的 URI 和 HTTP 头 部 ， 并 以 nginx.conf 中 
server_name 和 1location 等 配置 项 为 依据 ， 将 请 求 按照 其 所 在 阶段 准确 地 分 发 到 某 一 个 HITP 模 
块 ， 从 而 调用 它 的 回调 方法 来 处 理 该 请 求 。 


5) 同 HTTP 模 块 提 供 必 要 的 工具 方法 ， 可 以 处 理 网 络 WO【〔( 读 取 HTTP 包 体 、 友 送 HTTP 啊 
应 ) 和 磁盘 IO。 


6) 提供 upstream 机 制 帮助 HTTP 模 块 访问 第 三 方 服务 。 
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7) 提供 subrequest 机 制 帮 助 HTTP 模 块 实现 子 请 求 。 





HTTP 框 架 需 要 做 的 工作 很 多 ， 实 际 上 ，HTTP 的 框架 性 代码 也 是 极为 庞大 的 ， 为 了 简便 
起 见 ， 本 书 以 后 的 章节 将 专注 在 HTTP 框架 的 流程 代码 中 ， 完 全 不 会 涉及 具体 的 HTTP 功 能 模 
块 ， 也 不 会 涉及 框架 中 不 太 重 要 的 工具 性 的 代码 。 








本 章 会 完整 地 介绍 ngx_http_module 模 块 ， 其 中 涉及 少量 ngx_http_core_module 和 模块 的 功 
能 。 因 为 构成 HTTP 框 架 的 几 个 模块 间 的 代码 耦合 性 很 高 ， 所 以 对 于 HTTP 框 以 的 介绍 并 不 会 
按照 模块 进行 ， 而 是 从 HTTP 框 架 的 功能 和 架构 上 进行 ， 其 中 本 章 介 绍 Nginx 启 动 过 程 中 
HTTP 框 染 是 怎样 初始 化 的 ， 第 11 间 介绍 Nginx 运 行 过 程 中 HTTP 框 架 是 怎样 调度 HTTP 模 块 处 
理 请 求 的 ， 第 12 章 讲述 访问 第 三 方 服务 的 upstream 机 制定 如 何 工 作 的 。 
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10.1 _ HTTP 框架 概述 


为 了 让 读者 对 HTTP 框 架 所 要 完成 的 工作 有 一 个 直观 的 认识 ， 本 章 将 依托 一 个 贯穿 始终 
的 nginx.conf 配 置 范例 来 说 明 框 架 的 行为 ， 如 下 所 示 。 





http { 

mytest num 1; 

server { 
server name A; 
listen 127.0.0.1:8000; 
listen 80; 
mytest num 2; 
location /L1 { 


mytest num 3; 


location /L2 { 


mytest num 4; 
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server { 


server name B; 


listen 80; 


listen 8080; 


listen 173.39.160.51:8000; mytest num 5; 


location /L1 { 


mytest num 6; 


location /L3 { 


mytest num 7; 








从 上 面 这 个 简单 的 例子 中 ， 可 以 获取 下 列 信息 : 
. HTTP 框 架 是 支持 在 http 们 块 内 拥有 多 个 server{}、location{} 配置 块 的 。 


. 选择 使 用 哪 一 个 setvet 虚 拟 主 机 块 是 取决 于 setvet_hame 的 。 
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. 任意 的 server 块 内 都 可 以 用 listen 来 监听 端口 ， 在 不 同 的 server 块 内 允许 监听 相同 的 端 


. 选择 使 用 哪 一 个 location 块 是 将 用 户 请 求 URTI 与 合适 的 setvet 块 内 的 所 有 location 表 达 式 


做 匹配 后 决定 的 。 
` 同一 个 配置 项 可 以 出 现在 任意 的 http{}、server{}、location{} 等 配置 块 中 。 
HTTP 框 架 如 何 实现 上 述 的 配置 项 特性 呢 ? 


HTTP 框 架 的 首要 任务 是 通过 调用 ngx http _ module t 接 口中 的 方法 来 管理 所 有 HTTP 模 块 
的 配置 项 ，10.2 节 中 会 详细 描述 这 一 过 程 。 在 10.3 节 中 ， 我 们 会 探讨 监听 端口 与 server 虚 拟 主 
机 间 的 关系 ， 包 括 它 们 是 用 何 种 数据 结构 关联 在 一 起 的 。 所 有 的 server 虚 拟 主 机 会 以 散 列 表 
的 数据 结构 组 织 起 来 ， 以 达到 高 效 查 询 的 目的 ， 在 10.4 节 中 会 介绍 这 一 过 程 。 所 有 的 location 
表达 式 会 以 一 个 静态 的 二 又 查 找 树 组 织 起 来 ， 以 达到 高 效 查 询 的 目的 ， 在 10.5 节 中 会 说 明 
它 。 对 于 每 一 个 HTTP 请 求 ， 都 会 以 流水 线形 式 划 分 为 多 个 阶段 ， 以 供 HTTP 模 块 插入 到 
HTTP 框 架 中 来 共同 处 理 请 求 ，10.6 节 中 会 说 明 这 些 阶段 划分 、 实 现 的 依据 所 在 。 在 10.7 节 
中 ， 将 会 完整 地 说 明 在 Nginx 启 动 过 程 中 ，HTTP 框 架 是 如 何 初始 化 的 。 











下 面 开 始 介绍 ngx http _ module t 接 口 的 相关 内 容 。 


ngx_http_ module 核 心 模块 定义 了 新 的 模块 类 型 NGX _ HTTP MODULE。 这 样 的 HTTP 模 块 
对 于 ctx 上 下 文 使 用 了 不 同 于 核心 模块 、 事 件 模块 的 新 接口 ngx_http_module ft， 虽然 第 3 章 中 
经 提 到 过 ngx_http_module t 接 口 的 定义 ， 但 那 时 我 们 介绍 的 角度 是 如 何 开发 一 个 HTTP 模 块 ， 
现在 探讨 实现 HTTP 框 架 时 ， 对 ngx_ http module t 接 口 的 解读 就 不 同 了 。 在 重新 解读 
ngx_http_ module {接口 之 前 ， 先 对 不 同 级 别 的 HTTP 配 置 项 做 个 缩写 名 词 的 定义 : 


直接 隶属 于 http{} 块 内 的 配置 项 称 为 main 配 置 项 。 
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直接 隶属 于 location{} 块 内 的 配置 项 称 为 loc 配 置 项 。 
其 他 配置 块 本 章 不 会 涉及 ， 因 为 它们 与 HTTP 框 架 没 有 任何 关系 。 


对 于 每 一 个 HTTP 模 块 ， 都 必须 实现 ngx_http_module t 接 口 。 下 面 将 从 HTTP 框 架 的 角度 
来 进行 重新 解读 ， 如 下 所 示 。 





typedef struct { 


// 在 解析 


http{...} 内 的 配置 项 前 回调 


ngx int t (*preconfiguration) (ngx conf t *cf); // 解析 完 


http{...} 内 的 所 有 配置 项 后 回调 


ngx int t (*postconfiguration) (ngx conf 七 *cf); /* 创 建 用 于 存储 


HTTP 全 局 配置 项 的 结构 体 ， 该 结构 体 中 的 成 员 将 保存 直属 于 


http{} 块 的 配置 项 参数 。 它 会 在 解析 


main 配 置 项 前 调用 
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*/ 


void *(*create main conf) (ngx conf t *cf); // 解析 完 


main 配 置 项 后 回调 


char *(*jnit main conf) (ngx conf 七 cf, void conf); /* 创 建 用 于 存储 可 同时 出 现在 


main、 


srv 级 别 配 置 项 的 结构 体 ， 该 结构 体 中 的 成 员 与 


server 配 置 是 相关 联 的 


a 


void *(*create srv conf) (ngx conf 七 *cf); /*create srv conf 产生 的 结构 体 所 要 解析 的 配置 项 ， 可 能 同时 出 现在 


main、 


srv 级 别 中 ， 


merge_srv_conf 方 法 可 以 把 出 现在 
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main 级 别 中 的 配置 项 值 合并 到 


srv 级 别 配 置 项 中 
6 


char *(*merge srv conf) (ngx conf 七 cf, void prev, void *conf); /* 创 建 用 于 存储 可 同时 出 现在 


main、 


SIV、 


loc 级 别 配 置 项 的 结构 体 ， 该 结构 体 中 的 成 员 与 


location 配 置 是 相关 联 的 
*/ 


void *(*create loc conf) (ngx conf tt *cf); /*create loc conf 产 生 的 结构 体 所 要 解析 的 配置 项 ， 可 能 同时 出 现在 


main、 
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loc 级 别 中 ， 


merge loc conf 方 法 可 以 分 别 把 出 现在 


main、 


srv 级 别 的 配置 项 值 合并 到 


loc 级 别 的 配置 项 中 
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char *(*merge loc conf) (ngx conf t cf void prev, void *conf); } ngx http module t; 





可 以 看 到 ，ngx http module t 接 口 完全 是 围绕 着 配置 项 来 进行 的 ， 这 与 第 8 章 提 到 过 的 可 
定制 性 、 可 扩展 性 等 架构 特性 是 一 致 的 。 每 一 个 HTTP 模 块 都 将 根据 main、srv、loc 这 些 不 同 
级 别 的 配置 项 来 决定 自己 的 行为 。 





TiNNiNnnn http://wWwWw linuxorobe.con 





10.2 ”管理 HTTP 模 块 的 配置 项 


上 文 介绍 过 事件 配置 项 的 管理 ， 其 实 HTTP 配 置 项 的 管理 与 事件 模块 有 些 相 似 ， 但 由 于 
它 具 有 3 种 不 同 级 别 配 置 项 ， 所 以 巧 理 要 复杂 许多 。 对 于 HTTP 模 块 而 言 ， 只 需 关 心 工 作 时 能 
够 取 到 正确 的 配置 项 。 但 对 于 HTTP 框 架 而 言 ， 任 何 一 个 HTTP 模 块 的 server 相 关 的 配置 项 都 
是 可 能 出 现在 main 级 别 中 ， 而 location 相 关 的 配置 项 可 能 出 现在 main、srv 级 别 中 。 而 server 是 
可 能 存在 许多 个 的 ，location 更 是 可 以 反复 舱 套 的 ， 这 样 就 要 为 每 个 HTTP 模 块 按照 nginx.conf 
里 的 配置 块 建立 许多 份 配置 。 在 10.1 节 的 例子 中 ， 共 出 现 了 7 个 配置 块 ， 对 于 HTTP 框 架 而 
言 ， 就 需要 为 所 有 的 HTTP 模 块 分 配 7 个 用 于 存储 配置 结构 体 指针 的 数组 。 











在 处 理 http{} 块 内 的 main 级 别 配 置 项 时 ， 对 每 个 HTTP 模 块 来 说 ， 都 会 调用 
create main conf、create srv_conf、create loc_conf 人 方法 建立 3 个 结构 体 ， 分 别 用 于 存储 HTTP 
全 局 配置 项 、server 配 置 项 、location 配 置 项 。 现 在 问题 来 了 ，http{} 内 的 配置 项 明明 就 是 main 
级 别 的 ， 有 了 create_ main conf 生 成 的 结构 体 已 经 足够 保存 全 局 配置 项 参数 了 ， 为 什么 还 要 调 
用 create_srv_conf、create loc_conf 方 法 建立 结构 体 呢 ? 其 实 ， 这 是 为 了 把 同时 出 现在 http 但 、 
server{} 、location{} 内 的 相同 配置 项 进行 合并 而 做 的 准备 。 假 设 有 一 个 与 server 相 关 的 配置 
项 (例如 负责 指定 每 个 TCP 连 接 上 内 存 池 大 小 的 connection_pool_size 配 置 项 ) 同时 出 现在 
http{}、server{} 中 ， 那 么 对 它 感 兴趣 的 HTTP 模 块 就 有 权 决 定 srv 结 构 体 内 的 成 员 究 竞 是 以 
main 级 别 配 置 项 为 准 ， 还 是 srv 级 别 配置 项 为 准 。 结 合 10.1 市 的 例子 来 看 ，mytest_num 出 现在 
http{} 下 时 参数 为 1， 出 现在 server Af} 下 时 参数 为 2， 那 么 ，mytest 模 块 就 有 权 决 定 ， 当 处 理 
server A 虚 拟 主机 时 ， 究 竟 是 把 mytest num 参数 当 做 1 还 是 2， 或 者 把 它们 俩 相 加 ， 这 都 是 任何 
一 个 HTTP 模 块 的 自由 。 对 于 HTTP 框 架 而 言 ， 在 解析 main 级 别 的 配置 项 时 ， 必 须 同时 创建 3 
个 结构 体 ， 用 于 合并 之 后 会 解析 到 的 server、location 相 关 的 配置 项 。 


对 于 server{} 块 内 配置 项 的 处 理 ， 需 要 调用 每 个 HTTP 模 块 的 create srv_conf 方 法 、 
create_ loc_conf 方 法 建立 两 个 结构 体 ， 分 别 用 于 存储 server、location 相 关 的 配置 项 ， 其 中 
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create_ loc_confr 生 的 结构 体 仅 用 于 合并 location 相 关 的 配置 项 。 





对 于 location 块 内 配置 项 的 处 理 则 简单 许多 ， 只 需要 调用 每 个 HTTP 模 块 的 create_loc_conf 
方法 建立 1 个 结构 体 即 可 。 


结合 10.1 节 中 nginx.conf 配 置 文件 的 片断 来 看 ， 实 际 上 HTTP 框 架 最 多 必须 为 一 个 HTTP 模 
块 《〈 如 mytest 模 块 ) 创建 3+2+1+1+2+1+1=11 个 配置 结构 体 ， 而 经 过 合并 后 实际 上 每 个 HTTP 
模块 会 用 到 的 结构 体 有 7 个 。 可 为 什么 mytest 模 块 使 用 ngx_http_mytest_conf t 结 构 体 时 好 像 只 
有 1 个 配置 结构 体 呢 ? 因为 在 HTTP 框架 处 理 到 某 个 阶段 时 ， 例 如 ， 在 寻找 到 适合 的 location 
前 ， 如 果 试 图 去 取 ngx_http_mytest_conf t 结 构 体 ， 得 到 的 将 是 srv 级 别 下 的 配置 ， 而 寻找 到 
location 后 ，ngx_http_mytest_conf t 结 构 体 中 的 成 员 将 是 loc 级 别 下 的 配置 。 











下 面 介绍 一 下 ngx_http_module 模 块 在 实现 上 是 如 何 体现 上 述 思 路 的 。 


10.2.1 ”管理 main 级 别 下 的 配置 项 


上 文 说 过 ， 在 解析 HTTP 模 块 定义 的 main 级 别 配置 项 时 ， 将 会 分 别 调用 每 个 HTTP 模 块 的 
create main conf、create srv_conf、create loc_conf 方 法 建立 3 个 结构 体 ， 分 别 用 于 存储 全 
局 、server 相 关 的 、location 相 关 的 配置 项 ， 但 它们 究竟 是 以 何 种 数据 结构 保存 的 呢 ? 与 核心 
结构 体 ngx_cycle t 中 的 conf ctx 指 针 双 有 什么 样 的 关系 呢 ? 在 网 10-10 中 的 第 2 步 ~ 第 7 步 包含 了 
解析 main 级 别 配 置 项 的 所 有 流程 ， 而 图 10-1 将 会 展现 它们 在 内 存 中 的 布局 ， 可 以 看 到 ， 其 中 
ngx_http_core_module 模 块 完成 了 HTTP 框 架 的 大 部 分 功能 ， 而 它 又 是 第 1 个 HTTP 模块 ， 
此 ， 它 使 用 到 的 3 个 结构 体 (ngx http core main conf t、ngx http core Srv_conf ft、 
ngx_http_core loc_conf ft) 也 是 用 户 非常 关心 的 。 











图 10-1 中 有 一 个 结构 体 叫 做 ngx_http_conf_ctx_t， 它 是 HTTP 框 架 中 一 个 经 常用 到 的 数据 
结构 ， 下 面 看 看 它 的 定义 。 


wn httpo://ww | inuxorobe. con 





/* 指 向 一 个 指针 数组 ， 数 组 中 的 每 个 成 员 都 是 由 所 有 


HTTP 模 块 的 


create main conf 方 法 创建 的 存放 全 局 配置 项 的 结构 体 ， 它 们 存放 着 解析 直属 


http{} 块 内 的 


main 级 别 的 配置 项 参数 
*y 
void **main conf; 


/* 指 向 一 个 指针 数组 ， 数 组 中 的 每 个 成 员 都 是 由 所 有 


HTTP 模 块 的 


create srv_conf 方 法 创建 的 与 


server 相 关 的 结构 体 ， 它 们 或 存放 


main 级 别 配 置 项 ， 或 存放 
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srv 级 别 配 置 项 ， 这 与 当前 的 


ngx http conf ctx 七 是 在 解析 





http{} 或 者 


server{} 块 时 创建 的 有 关 
*/ 
void **srv conf; 
/* 指 向 一 个 指针 数组 ， 数 组 中 的 每 个 成 员 都 是 由 所 有 
HTTP 模 块 的 
create loc conf 方 法 创建 的 与 


location 相 关 的 结构 体 ， 它 们 可 能 存放 着 


main、 
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loc 级 别 的 配置 项 ， 这 与 当前 的 


ngx http conf ctx 七 是 在 解析 





http{}、 


server{} 或 者 


location{} 块 时 创建 的 有 关 


void **]oc conf; 


} ngx http. conf ctx t>; 





ngx_ http_conf ctx t 中 仅 有 3 个 成 员 ， 它 们 分 别 指 癌 3 个 指针 数组 。 在 10.2.4 节 中 ， 读 者 会 
看 到 srv_conf 数 组 和 loc_conf 数 组 在 配置 项 的 合并 操作 中 是 如 何 使 用 的 。 


在 核心 结构 体 ngx_cycle_t 的 conf_ctx 成 员 指 向 的 指针 数组 中 ， 第 7 个 指针 由 
ngx_http module 模 块 使 用 (ngx_http_module 模 块 的 index 序 号 为 6， 由 于 由 0 开始 ， 所 以 它 在 
ngx_modules 数 组 中 排行 第 7。 在 存放 全 局 配置 结构 体 的 conf_ctx 数 组 中 ， 第 7 个 成 员 指向 
ngx_http_module 模 块 )， 这 个 指针 设置 为 指向 解析 http 们 块 时 生成 的 ngx_http_conf_ctx 结构 
体 ， 而 ngx_http_conf ctx t 的 3 个 成 员 则 分 别 指向 新 分 配 的 3 个 指针 数组 。 新 的 指针 数组 中 成 员 
的 意义 由 每 个 HTTP 模 块 的 ctx_index 序 号 指定 (ctx_index 在 HTTP 模 块 中 表明 它 处 于 HTTP 模 块 
间 的 序号 ) ， 例 如 ， 第 6 个 HTTP 模 块 的 ctx index 是 5 (ctx index 同 样 由 0 开始 计数 ) ， 那 么 在 
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negx_http_conf ctx t 的 3 个 数组 中 ， 第 6 个 成 员 就 指 癌 第 6 个 HTTP 模 块 的 create_main conf、 
create_STV_conf、create loc_conf 方 法 建立 的 结构 体 ， 当 然 ， 如 果 相 应 的 回调 方法 没有 实现 ， 
该 指针 就 为 NULL 空 指针 。 
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ngx_cycle tt 


所 有 核心 模块 的 配置 结构 体 指针 | | 


conf_ctx 


PO 
TTTITIT | 
Ee a 


pe ngx_modules 数 组 可 以 看 出 ， 第 7 个 模块 是 
ngx_http_module 模 块 ，conf_ctx 数 组 中 第 7 位 存储 


着 Ngx_http_module 模 块 的 配置 项 指针 ， 在 这 里 ， 
这 个 指针 被 定义 为 指向 ngx_http_conf_ctx_t 结 构 体 





ngx_http_conf_ctx_t 结 构 体 





ngx_http_core_main_conf_t 





create_main _conf 
生成 的 结构 体 指 针 


ngx_http_core_loc_conf 1 
C—O 


create_srv_conf 


生成 的 结构 体 指针 


Fl 第 6 个 HTTP 模 块 create_main_conf t 结 构 体 


create_loc_conf 


生成 的 结构 体 指针 





第 6 个 HTTP 模 块 creat e_srv_conf + 结构 体 





第 6 个 HTTP 模 块 create_loc_conf t 结 构 体 


图 10-1 HTIP 框 架 解 析 main 级 别 配置 项 时 配置 结构 体 的 内 存 示 意图 


ngx_http_core_module 模 块 是 第 1 个 HTTP 模 块 ， 它 的 ctx_index 序 号 是 09， 因 此， 数组 中 的 
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第 1 个 指针 将 指 同 ngx_http_core_ module 模块 生成 的 ngx_http core main conf ft、 
ngx http core srv conf t、ngx http core loc_conf t 结 构 体 。 


可 如 何 由 ngx_cycle t 核 心 结构 体 中 找到 main 级 别 的 配置 结构 体 呢 ? Nginx 提 供 的 
ngx_http_cycle_get module main conf 宏 可 以 实现 这 个 功能 ， 如 下 所 示 。 





i#define ngx http cycle get module main conf (cycle, module) \\ 





(cycle->conf ctx[ngx http module.index] \ 


((ngx. http. Gont. etx tt *) 





Cycle->conf ctx[ngx http module.index]) 


->main conf[module.ctx index]: \ 


NULL) 





其 中 参数 cycle 是 ngx_cycle t 核 心 结构 体 指 针 ， 而 module 则 是 所 要 操作 的 HITP 模 块 。 它 的 
实现 很 简单 ， 先 由 cycle 的 conf ctx 指 针 数 组 中 找到 ngx_http_ module.index 序 号 〈 上 文 说 过 ， 其 
index 为 6) 对 应 的 指针 ， 获 取 到 http 儒 块 下 的 ngx_http_conf ctx 城 员 ， 然 后 经 由 main_conf 数 组 
即 可 找到 所 有 HTTP 模 块 的 main 级 别 配 置 结构 体 。 最 后 ， 根 据 所 要 查询 的 module 数 组 的 
ctx_index 序 号 取得 其 main 级 别 下 的 配置 结构 体 ， 例 如 ; 





ngx http Perl main conf 七 xpmcf = ngx http cycle get module main conf (Cycle，ngx http perl module); 











er 注意 HTIP 全 局 配置 项 是 基础 ， 管 理 server、location 等 配置 块 时 取决 于 
ngx_http_core_module 模 块 出 现在 main 级 别 下 存储 全 局 配置 项 的 ngx_http_core_main_conf t 结 构 
体 。 


10.2.2 ”管理 server 级 别 下 的 配置 项 . 
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在 解析 main 级 别 配 置 项 时 ， 如 果 发 现 了 server 人 {} 配 置 项 ， 就 会 回调 ngx http core server 方 
法 (该 方 法 属于 ngx_http_core module 模 块 )， 而 在 这 个 方法 里 则 会 开始 解析 srv 级 别 的 配置 
项 ， 其 流程 如 图 10-2 所 示 。 


下 面 简要 说 明 图 10-2 中 的 步骤 : 


1) 在 解析 到 server 块 时 ， 首 先 会 像 解析 http 块 一 样 ， 建 立 属于 这 个 server 块 的 
0 
下 ngx_http_conf ctx {结构 体 的 main_conf 指 针 数 组 ， 而 srv_confHloc_conf 都 将 重新 分 配 指针 数 
组 ， 数 组 的 大 小 为 ngx_http max_module， 也 就 是 所 有 HTTP 模 块 的 总 数 。 


2) 循环 调用 所 有 HTTP 模 块 的 create_ srv_conf 方 法 ， 将 返回 的 结构 体 指针 按照 模块 序号 
ctx_index 保 存 到 上 述 的 srv_conf 指 针 数 组 中 。 


3) 循环 调用 所 有 HTTP 模 块 的 create loc_conf 方 法 ， 将 返回 的 结构 体 指 针 按 照 模块 序号 
ctx_ index 保 存 到 上 述 的 loc_conf 指 针 数 组 中 。 


4) 第 1 个 HTTP 模 块 就 是 ngx http_ core module 模 块 ， 它 在 create_srv_conf 方 法 中 将 会 生成 
非常 关键 的 ngx_http_core_srv_conf t 配 置 结构 体 ， 这 个 结构 体 对 应 着 当前 正在 解析 的 server 
块 ， 这 时 ， 将 ngx_http_core_srv_conf {t 添 加 到 全 局 的 ngx http_ core _ main conf t 结 构 体 的 servers 
动态 数组 中 ， 在 图 10-3 中 会 看 到 这 一 点 。 
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1 ) 分 配 存 放 srv 级 别 配置 项 指针 的 
两 个 数组 


2 ) 调用 所 有 HTTP 模 块 的 


create_sry_conf 方 法 


3 ) 调用 所 有 HTIP 模 块 的 


create loc con{ 方法 


—、 


4 ) 将 属于 当前 server 抉 的 ngx_http _core _srv_conf_i 
添加 到 servers 动态 数组 中 


5 ) 解析 当前 server 块 下 的 全 部 
| 


srV 级 别 配 置 项 


6 ) 如 果 没 有 listen 选项 ， 则 监听 
默认 的 80 端 口 





全 


图 10-2 解析 server{} 块 内 配置 项 的 流程 


5) 解析 当前 server 人 块 内 的 所 有 配置 项 。 





6) 如 果 在 server{} 块 内 没有 解析 到 listen 配 置 项 ， 则 意味 着 当前 的 server 虚 拟 主机 并 没有 
监听 TCP 端 口 ， 这 不 符合 HITP 框 架 的 设计 原则 。 于 是 将 开始 监听 默认 端口 80， 实 际 上 ， 如 
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果 当 前 进程 没有 权限 监听 1024 以 下 的 端口 ， 则 会 改 为 监听 8000 端 口 。 


由 于 http 块 只 有 1 个 ， 因 此 在 10.2.1 节 中 可 以 简单 地 给 出 main 级 别 配置 项 的 内 存 示 意 几 。 
但 http 块 内 会 包含 任意 个 server 块 ， 对 于 每 个 server 块 都 需要 建立 1 个 ngx_http_conf ctx t 结 构 
体 ， 这 些 server 块 的 ngx_http_conf ctx t 结 构 体 是 通过 ngx_array 动态 数组 组 织 起 来 的 ， 这 其 中 
的 关系 就 比较 复杂 了 ， 图 10-3 是 它们 简单 的 内 存 示 意图 。 
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ngx_cycle_1 


所 有 核心 模块 的 配置 结构 体 指针 | 
onf cx 


/ conf_ctx 


ngx_http_conf_ctx_t 结 构 体 


- - ngx_http_core_main_conf_t 
main_conf srv_conf 


可 画 画 国 本 国 状 男 画 便 四 











http 块 下 ereate_main__conf 配置 项 指针 


servers 数 组 中 指针 皆 指 癌 一 属于 server A 块 


ngx_nttp _core _srv _conf + 


server A 块 下 


ngx_http_conf_ctx_t 绪 构 体 


ngx_http_core_srv_conf_+ 


| 
ee 


server A 块 下 各 模块 
create_srv_conf 生成 的 结构 体 指 针 


server A 块 下 各 模块 
create_loc_conf 生 成 的 结构 体 指 针 


server B 块 下 ngx_http_conf_ctx_t 结 构 体 














图 10-3 HTIP 模 块 srv 级 别 配置 项 结构 体 指 针 的 内 存 示 意图 
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图 10-3 是 针对 10.1 节 中 的 例子 所 画 的 示意 图 ， 在 http 块 下 有 两 个 server 块 ， 分 别 表示 虚 拟 
主机 名 为 A 的 配置 块 和 虚拟 主机 名 为 B 的 配置 块 。 解 析 每 一 个 server 块 时 都 会 创建 一 个 新 的 
ngx_http_conf ctx t 纤 构 体 ， 其 中 的 main conf 将 指 网 http 块 下 main_ conf 指 针 数 组 ， 而 srv_conf 和 
loc_conf 数 组 则 都 会 重新 分 配 ， 它 们 的 内 容 就 是 所 有 HTTP 模 块 的 create_srv_conf 方 法 、 
create loc_conf 方 法 创建 的 结构 体 指针 。 


在 10.2.1 节 中 提 到 的 main 级 别 配置 项 中 ，ngx_http_core_ module 模块 的 
ngx_http_core main conf t 结 构 体 中 有 一 个 servers 动 态 数 组 ， 如 下 所 示 。 





typedef struct { 


/* 存 储 指针 的 动态 数组 ， 每 个 指针 指向 


ngx http core srv conf 苇 结 构 体 的 地 址 ， 也 就 是 其 成 员 类 型 为 





ngx http core srv conf 七 xx */ 





ngx array t servers; 


} ngx http core main conf t; 








servers 动 态 数 组 中 的 每 一 个 元 系 都 是 一 个 指针 ， 它 指向 用 于 表示 server 块 的 
ngx http_core_srv_conf t 结 构 体 的 地 址 (属于 ngx_http_core module 模 块 ) 。 
ngx http core srv_conf t 结 构 体 中 有 1 个 ctx 指 针 ， 它 指 辣 解 析 server 块 时 新 生成 的 
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ee 一 | 


typedef struct { 


// 指向 当前 


server 抉 所 属 的 


ngx http conf ctx 七 结构 体 





ngx http. conf ctx tt *otx: 





/* 当 前 


server 块 的 虚拟 主机 名 ， 如 果 存 在 的 话 ， 则 会 与 


HTTP 请 求 中 的 


Host 头 部 做 匹配 ， 匹 配 上 后 再 由 当前 


ngx http core srv conf 七 处 理 请 求 





* 


ngx str 七 server name; 
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} ngx http core srv conf t; 





这 样 ，server 块 下 以 ngx_http_conf ctx tt 组 织 起 来 的 所 有 配置 项 结构 体 ， 就 会 由 servers 动 
态 数 组 关联 起 来 。servers 动 态 数 组 中 的 元 素 个 数 与 http 块 下 的 server 配 置 块 个 数 是 一 致 的 。 


10.2.3 ”管理 location 级 别 下 的 配置 项 


在 解析 srv 级 别 配 置 项 时 ， 如 果 发 现 了 location 们 配置 块 ， 就 会 回调 ngx http_core location 
方法 (该 方法 属于 ngx_http_core module 模 块 ) ， 在 这 个 方法 里 则 会 开始 解析 loc 级 别 的 配置 


项 ， 其 流程 如 图 10-4 所 示 。 
下 面 简 要 介绍 一 下 图 10-4 中 的 流程 : 


1) 在 解析 到 location 人 配置 块 时 ， 仍 然 会 像 解析 http 块 一 样 ， 先 建立 ngx_http_conf ctx t 结 
构 体 ， 只 是 这 里 的 main conf 和 srv_conf 痢 将 指 癌 所 属 的 server 块 下 ngx http_conf ctx tt 结构 体 的 
main conf 和 srv_conf 指 针 数 组 ， 而 loc_conf 则 将 指向 重新 分 配 的 指针 数组 。 


2) 循环 调用 所 有 HTTP 模 块 的 create loc conf 方 法 ， 将 返回 的 结构 体 指 针 按 照 模块 序号 
ctx_index 保 存 到 上 述 的 loc_conf 指 针 数 组 中 。 


3) 如 果 在 location 中 使 用 了 正则 表达 式 ， 那 么 这 时 将 调用 pcre_compile 方 法 预 编 译 正 则 表 
达 式 ， 以 提高 性 能 。 


4) 第 1 个 HTTP 模 块 是 ngx_ http_core_ module 模块 ， 它 在 create loc_conf 方 法 中 将 会 生成 
ngx_http_core_ loc_conf t 配 置 结构 体 ， 可 以 认为 该 结构 体 对 应 着 当前 解析 的 location 块 。 这 时 
会 生成 ngx_http_location_queue_t 结 构 体 ， 因 为 每 一 个 ngx_http_core_loc_conf it 结构 体 都 对 应 着 
1 个 ngx_http location queue t， 因 此 ， 此 处 将 把 ngx http location queue tt 串联 成 双 同 链表 ， 在 
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图 10-5 中 会 看 到 这 一 点 。 










1 ) 分 配 用 于 存放 loc 级 别 配置 项 指针 的 1 个 数组 














pp 调用 有 所 有 模块 的 create _loc_conf 方 法 


| 当前 location 后 的 表达 式 是 否 使 用 正则 表达 式 | 


[没有 使 用 正则 表达 式 ] 
[使 用 了 正则 表达 式 ] 


) 预 编译 正则 表达 式 


4) 建 并 ngx_http location_queuet 并 添加 到 双 回 链表 





和 ) 解析 妆 人 location 下 的 所 有 有 loc : 级 别 配 置 项 





图 10-4 解析 location{} 配 置 块 的 流程 
5) 解析 当前 location{} 配 置 块 内 的 loc 级 别 配 置 项 。 


图 10-5 为 HTTP 模 块 loc 级 别 配 置 项 结构 体 指针 的 内 存 示 意图 。 


OE Tv 不 过 和 LE 











A《〈 其 server_name 的 参数 值 为 A) 以 及 它 所 属 的 locationL1 块 。 在 解析 http 块 时 曾 创建 过 1 个 
ngx_http_core loc_ conf t 结 构 体 〈 见 10.2.1 节 ) ， 在 解析 server 块 A 时 曾经 创建 过 1 个 
ngx_http_core_ loc_conf t 结 构 体 〈 见 10.2.2 节 ) ， 而 解析 其 下 的 location 块 Ll 时 也 创建 了 
ngx_http_core_loc_conf t 结 构 体 ， 从 图 10-5 中 可 以 看 出 这 3 个 结构 体 间 的 关系 。 下 面 先 看 看 图 
10-5 中 ngx http core loc conf t 的 3 个 关键 成 员 : 





typedef struct ngx http core loc conf s ngx http core loc conf 七 struct ngx http core loc conf s { 








// location 的 名 称 ， 即 


nginx.conf 中 


location 后 的 表达 式 


ngx_ str t name; 


/* 指 向 所 属 


location 块 内 


ngx http conf ctx 七 结构 体 中 的 





loc_conf 指 针 数 组 ， 它 保存 着 当前 
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location 块 内 所 有 


HTTP 模 块 


create 1oc_conf 方 法 产生 的 结构 体 指针 


2 


void **loc conf; 


SerVeLr 块 内 多 个 表达 


location 块 的 


ngx http core loc conf 七 结构 体 以 双向 链表 方式 组 织 起 来 ， 该 





locations 指 针 将 指向 


ngx http location queue 七 结构 体 
*/ 


ngx queue 七 *locations; 
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ngx_cycle_t 


所 有 核心 模块 的 配置 结构 体 指 针 


=m 
曙 曾 闻 本 本 本 靖 面 


ngx_http_conf_ctx_+ 结 构 体 


http 块 下 create_main_conf 配置 项 指针 


conf _ctx 





ngx_http_core_main_conf + 


SETVETS 















servers 数 组 中 指针 皆 指 癌 
ngx_http _core _srv _conf _1 


server A 块 下 


ngx_http_core_srv_conf + 


~ 
一 
” 


server A 块 下 create_STV 


_eonf 生成 的 结构 体 指针 
LT 
ngx_http_core_loc_conf_t 


server A 块 下 create_loc_conf 


生成 的 结构 体 指针 


一 
location L 1 抉 下 ngx_http_conf_ctx_t 结 构 体 


i 属于 location Ll1 块 
| ee 
ee 


location 上 L 1 块 下 create_loc_conf 生 成 的 结构 体 指针 
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loc_conf 


ngx_http_core_loc_conf 





图 10-5 HTTP 模 块 loc 级 别 配 置 项 结构 体 指针 的 内 存 示意 图 


可 以 这 么 说 ，ngx_http_core_loc_conf t 拥 有 足够 的 信息 来 表达 1 个 location 块 ， 它 的 
loc_conf 成 员 也 可 以 引用 到 各 HTTP 模 块 在 当前 location 块 中 的 配置 项 。 所 以 ， 一 旦 通过 某 种 容 
器 将 ngx_http core loc_conf t 组 织 起 来 ， 也 就 是 把 location 级 别 的 配置 项 结构 体 管 理 起 来 了 。 

但 ngx_http_core loc_conf { 又 是 放置 在 什么 样 的 容器 中 呢 ? 注意 ， 图 10-3 在 解析 server 抉 A 时 
有 1 个 ngx _http_core loc_conf t 结 构 体 ， 它 的 地 位 与 server 块 A 内 的 各 个 location 块 对 应 的 
ngx_http_core_loc_conf t 结 构 体 是 不 同 的 ，location L1、location L2 块 内 的 
ngx_http_core_loc_conf t 是 通过 server A 块 内 产生 的 ngx_http_core_loc_conf t 关 联 起 来 的 。 


在 ngx_http_core_loc_conf tt 结构 体 中 有 一 个 成 员 locations， 它 表示 属于 当前 块 的 所 有 
location 块 通过 ngx http location queue t 结 构 体 构成 的 双 问 链表， 如 下 所 示 。 





typedef struct { 


/xcueue 将 作为 


ngx_queue 七 双向 链表 容器 ， 从 而 将 


ngx_ http location queue 七 结构 体 连 接 起 来 


ngx queue 七 queue; 


/* 如 果 


location 中 的 字符 串 可 以 精确 匹配 (包括 正则 表达 式 ) ， 
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exact 将 指向 对 应 的 


ngx http core loc conf 鞋 结构 体 ， 否 则 值 为 





NULL*/ 


ngx http core loc conf 七 *exact; 





/* 如 果 


location 中 的 字符 串 无 法 精确 匹配 (包括 了 自 定 义 的 通配符 ) ， 


inclusive 将 指向 对 应 的 


ngx http core loc conf 鞋 结构 体 ， 否 则 值 为 





NULL*/ 


ngx http core loc conf 七 *inclusive; 





// 指向 


location 的 名 称 
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ngx str 七 *name; 


} ngx http location queue t; 


可 以 看 到 ，ngx http location queue t 中 的 queue 成 员 将 把 所 有 相关 的 
ngx http location queue tt 结构 体 串 联 起 来 。 同 时 ，ngx http location queue 将 帮助 用 户 把 所 有 
的 location 块 与 其 所 属 的 server 块 关联 起 来 。 





那么 ， 哪 些 ngx_http location queue tt 结构 体会 被 串联 起 来 呢 ? 还 是 看 10.1 节 的 例子 ， 
server 块 A 以 及 其 下 所 属 的 location L1 和 location L2 共 包括 3 个 ngx http core loc conf tt 结构 体 ， 
它们 是 相关 的 ， 下 面 看 看 它们 是 怎样 天 联 起 来 的 ， 如 图 10-6 所 示 。 


每 一 个 ngx_http_core_loc_conf t 都 将 对 应 着 一 个 ngx_http_location_queue tt 结构 体 。 在 
server 块 A 拥有 的 ngx_http_core_loc_conf t 结 构 体 中 ，locations 成 员 将 指向 它 所 属 的 
ngx_http_location_ queue_t 结 构 体 ， 这 是 1 个 双向 链表 的 首部 。 当 解析 到 location L1 块 时 ， 会 创 
建 一 个 ngx_http_location queue t 结 构 体 并 添加 到 locations 双 向 链表 的 尾部 ， 该 
ngx_http location queue tt 结构 体 中 的 exact 或 者 inclusive 指 针 将 会 指 同 location LI 所 属 的 
ngx_http_core_loc_conf t 结 构 体 〈 在 location 后 的 表达 式 属 于 完全 匹配 时 ，exact 指 针 有 效 ， 否 
则 表达 式 将 带 有 通配符 ， 这 时 inclusive 有 效 。exact 优 先 级 高 于 inclusive) ， 这 样 就 把 location 
L1 块 对 应 的 ngx_http_core_loc_conf t 绪 构 体 ， 以 及 其 loc_conf 成 员 指向 的 所 有 HTTP 模 块 在 
location LI1 块 内 的 配置 项 与 server A 块 结合 了 起 来 。 解 析 到 location L2 时 会 做 相同 处 理 ， 这 也 
就 得 到 了 图 10-6。 
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属于 server A 块 

















ngx_http _core _loc _conf 1t 


server A 块 下 create_loc_conf 配 置 项 指针 


ngx_http_location_queue_t 


dueue 


exact 
inclusive 








ngx_http _ core _loc _ 


ngx_http_location_queue_t 


dueue 


inclusive 


















ngx_http _core_loc _conf _+ 





属于 location L2 块 


ngx_http _ location_queue_t 


dueue 
exact 
inclusive 


图 10-6 ”同一 个 server 块 下 的 ngx_http_core_loc_conf ft 是 通过 双向 链表 关联 起 来 的 
事实 上 ，location 之 间 是 可 以 舱 套 的 ， 那 么 它们 之 间 的 关联 关系 又 是 怎样 的 呢 ? 扩展 一 
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下 10.1 市 中 的 例子 ， 即 假设 配置 文件 如 下 : 





http. { 


mytest num 1; 


server { 


server name A; 


listen 8000; 


listen 80; 


mytest num 2; 


location /L1 { 


mytest num 3; 


location /LI1/CLL { 





这 时 多 了 一 个 新 的 location 块 L1/CL1， 它 隶属 于 location Ll1。 此 时 ， 每 个 location 块 对 应 的 
ngx_http_core_loc_conf t 结 构 体 间 是 通过 如 图 10-7 所 示 的 形式 组 织 起 来 的 。 
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属于 server A 块 












ngx_http _core_loc_conf_t 


ngx_http _core_ loc_conf tt 





server A 块 下 create_loc_conf 配 置 项 指针 














ngx_http _location _queue_t 


-Aan 






queue 


exact 
inclusive 


ngx_http _location_ queue_t 















属于 location Ll 块 






inclusive 


ngx_http _location_queue_t 
属于 location L1/CL1 块 


ngx_http _location_queue 1 









ngx_http _core _loc_conf _1 









exact 
inclusive 
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图 10-7 location 块 谱 套 后 ngx_http_core_loc_conf t 结 构 体 间 的 关系 





可 以 看 到 ， 仍 然 是 通过 ngx http_core loc_conf tt 结构 体 中 的 locations 指 针 来 容纳 属于 它 的 
location 块 的 。 当 1locations 为 空 指针 时 ， 表 示 当 前 的 location 块 下 不 再 极 套 location 块 ， 否 则 表 
示 还 有 新 的 location 块 。 在 10.2.4 节 的 合并 配置 项 的 代码 中 可 以 看 到 这 一 点 。 


10.2.4 ”不同 级 别 配 置 项 的 合并 


考虑 到 HTTP 模 块 可 能 需要 合并 不 同 级 别 的 同名 配置 项 ， 因 此 ，HTTP 框 架 为 
ngx_http_module t 接 口 提供 了 merge_srv_conf 方 法 ， 用 于 合并 main 级 别 与 srv 级 别 的 server 相 关 
的 配置 项 ， 同 时 ， 它 还 提供 了 merge_loc_conf 方 法 ， 用 于 合并 main 级 别 、srv 级 别 、loc 级 别 的 
location 相 关 的 配置 项 。 当 然 ， 如 果 不 存在 合并 不 同 级 别 配置 项 的 场景 ， 那 么 可 以 不 实现 这 
两 个 方法 。 下 面 仍然 以 10.1 节 的 配置 文件 为 例 ， 展 示 了 不 同 级 别 的 配置 项 结构 体 是 如 何 合并 
的 ， 如 图 10-8 所 示 。 
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I 解析 直属 于 http 块 下 的 main 配置 项 
“tt 


http 块 Fereate _main_conf 配置 项 指针 局 块 5 用 create _main_conf + 创建 的 结构 体 


国王 画图 丁 醒 昌林 
SB 


http 块 Fereate _srv_conf 配置 项 指针 


LE 模块 5 用 ereate_loc_conf_t 创 建 的 结构 体 


http 块 下 create _ loc _conf 配置 项 指针 






模块 5 用 create _srv _conf _t 创 建 的 结构 体 


I I es | i a i 解析 http 块 下 server A 的 配置 项 
“ey, 


server A 块 下 create _srv_conf 配置 项 指针 模块 5 用 create_srv_conf 1 创建 的 结构 体 


TT 模块 5 用 create_loc _conf_t 创 建 的 结构 体 


server A 块 下 create_loc _conf 配置 项 指针 


合并 





解析 http 块 下 server A 块 中 
location 工 1 的 配置 项 


L 
location 上 1 块 下 create_loc _conf 配置 项 指针 


图 10-8 main、Sstv、loc 级 别 的 同名 配置 项 合并 前 的 内 存 示意 图 


图 10-8 以 第 5 个 HTTP 模 块 (通常 是 ngx http static_ module 模 块 ) 为 例 ， 展 示 了 在 解析 完 

http 块 、server A 块 、location LI1 块 后 是 如 何 合并 配置 项 的 。 第 5 个 HTTP 模块 在 解析 这 3 个 配置 
块 时 ，create loc_conf 人 访 法 被 调用 了 3 次 ， 产 生 了 3 个 结构 体 ， 分 别 存放 了 main、sSrv、loc 级 
别 的 location 相 关 的 配置 项 ， 这 时 可 以 合并 为 location L1 相 关 的 配置 结构 体 ，create srv_conf t 
方法 被 调用 了 两 次 ， 产 生 了 两 个 结构 体 ， 分 别 存放 了 main、srv 级 别 的 配置 项 ， 这 时 也 可 以 合 


并 为 server A 块 相关 的 配置 结构 体 。 . 
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合并 配置 项 可 能 不 太 容 易 理 解 ， 下 面 我 们 就 在 代码 实现 层面 上 再 做 个 简要 的 介绍 ， 同 时 
也 对 10.2.2 节 和 10.2.3 贡 的 内 容 做 一 个 回顾 。 这 个 合并 操作 是 在 ngx_http_merge_servers 方 法 下 
进行 的 ， 先 来 简单 地 看 看 它 是 怎么 被 调用 的 : 








/*cmcf 是 


ngx_http core module 在 


http 块 下 的 全 局 配置 结构 体 ， 在 


servers 成 员 ， 这 是 一 个 动态 数组 ， 它 保存 着 所 有 


ngx http core srv conf 七 的 指针 ， 从 而 关联 了 所 有 的 





server 块 
#/ 


cmcf = ctx->main conf[ngx http core module.ctx index]; // ngx modules 数 组 中 包含 所 有 的 


Nginx 模 块 
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for (m= 0); ngx modules[m]; m++) { 


// 遍历 所 有 的 


HTTP 模 块 


if (ngx modules [m]->type != NGX HTTP MODULE 





一 


continue; 


/* ngx modules [m] 是 一 个 


ngx_module 七 模块 结构 体 ， 它 的 


ctx 成 员 对 于 


HTTP 模 块 来 说 是 


ngx_http module 七 接口 
Sy 


ngx http module t *module = ngx modules[m]->ctx; // ctx index 是 这 个 
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HTTP 模 块 在 所 有 


HTTP 模 块 中 的 序号 


mi = ngx modules[m]->ctx index; 


// 调用 


ngx http merge Servers 方法 合并 


ngx_ modqules [m] 模块 


TV = ngx http merge servers(cf, cmcf, module, mi); } 





ngx http merge servers 方 法 不 只 是 合并 了 server 相 关 的 配置 项 ， 它 同时 也 会 合并 location 
相关 的 配置 项 ， 下 面 再 来 看 看 它 的 实现 ， 代 码 如 下 。 





static char ngx http merge servers (ngx conf t cf, ngx http core main conf 七 cmcf, ngx http module t 





Ghar “EY 


ngx uint t s; 


ngx http conf ctx t *ctx, saved; 





ngx http core Loc conf 七 <CLCE， 
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ngx http core srv conf 七 **cscfp; 





/* 从 


ngx http core main conf 七 的 





servers 动 态 数 组 中 可 以 获取 所 有 的 


ngx http core srv conf 结构 体 








4 
CScfp = cmcf->servers.elts; 
// 注意 ， 这 个 
ctX 是 在 
http{} 块 下 的 全 局 
ngx http conf ctx 七 结构 体 
ctx = (ngx http conf ctx 七 *) cf->ctx; saved = *ctx; 





// 遍历 所 有 的 
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SerVver 块 下 对 应 的 


ngx http core srv conf 鞋 结构 体 





for (s = 0; s < cmcf->servers.nelts; s++) { 


/*srv_conf 将 指向 所 有 的 


HTTP 模 块 产 生 的 


server 相 关 的 


srv 级 别 配 置 结构 体 
*/ 


ctx->srv conf = cscfp[s]->ctx->srv conf; // 如 果 当 前 


HTTP 模 块 实现 了 


merge srv conf， 则 再 调用 合并 方法 


if (module->merge srv conf) { 
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/* 注 意 ， 在 这 里 合并 配置 项 时 ， 


saved.srv conf[ctx index] 参数 是 当前 


HTTP 模 块 在 


http{} 块 下 由 


create_srv_conf 方 法 创建 的 结构 体 ， 而 


cscfp[s]->ctx->srv_conf[ctx index] 参数 则 是 在 


server{} 块 下 由 


create srv _conf 方 法 创建 的 结构 体 


4 





rv = module->merge srv conf(cf, saved.srv conf[ctx index], cscfp[s]-> ctx->srv conf [ctx index]); } 


// 如 果 当 前 


HTTP 模 块 实现 了 
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merge srv conf， 则 再 调用 合并 方法 


if (module->merge loc conf) { 


/*cscfp[s]->ctx->loc conf 这 个 动态 数组 中 的 成 员 都 是 由 


server{} 块 下 所 有 


HTTP 模 块 的 


create loc_ conf 方法 创建 的 结构 体 指 针 


*y 


ctx->loc conf = cscfp[s]->ctx->loc conf; /* 首 先 将 


http{} 块 下 


main 级 别 与 


server{} 块 下 


srv 级 别 的 
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location 相 关 的 结构 体 合 并 


Wa 


rv = module->merge loc conf(cf, saved.loc conf[ctx index], cscfp[s]-> ctx->loc conf [ctx index]); /* 





server 块 下 


ngx_http core module 模 块 使 用 


create loc conf 方 法 产生 的 


ngx http core loc conf 七 结构 体 ， 在 





10.2.3 节 中 曾经 说 过 ， 它 的 


locations 成 员 将 以 双向 链表 的 形式 关联 到 所 有 当前 


server{} 块 下 的 


location 块 


*y 
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ngx_http _ merge _ locations 方 法 ， 将 


server{1} 块 与 其 所 包含 的 


location{} 块 下 的 结构 体 进行 合并 


4 


rv = ngx http merge locations(cf, clcf->locations, cscfp[s]->ctx->loc conf, module, ctx index); } 





ngx_http_merge_locations 方 法 负责 合并 location 相 关 的 配置 项 ， 上 面 已 经 将 main 级 别 与 srv 
级 别 做 过 合并 ， 接 下 来 再 次 将 srv 级 别 与 loc 级 别 做 合并 。 每 个 server 块 
ngx http_core loc_conf t 中 的 locations 双 回 链 表 会 包含 所 属 的 全 部 location 块 ， 壳 历 它 以 合并 
SIV、loc 级 别 配 置 项 ， 如 下 所 示 。 








static char 大 


ngx http merge locations (ngx conf 七 cf, ngx queue t locations, void **loc conf, ngx http module t *module, ngx 1 


char *rv; 


ngx queue 七 *q; 


ngx http conf ctx 七 *etx,y Saved; 





ngx http core loc conf 七 *clcf; 
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ngx http Location queue 七 *]qg; 


/* 如 果 


Locations 链 表 为 空 ， 也 就 是 说 ， 当 前 


server 块 下 没有 


location 块 ， 则 立刻 返回 





区/ 
if (locations == NULL) { 
return NGX CONF OK; 
} 
ctx = (ngx http conf ctx 七 *) cf->ctx; saved = *ctx; 
// 遍历 
locations 双 向 链表 
for (gq = ngx queue head (locations); 
q != ngx queue sentinel (locations); gq = ngx queue next (9q)) 
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lq = (ngx _ http Location queue t *) q; /* 在 


10.2.3 节 中 曾经 讲 过 ， 如 果 


location 后 的 匹配 字符 串 不 依靠 


Nginx 自 定义 的 通配符 就 可 以 完全 匹配 的 话 ， 则 


exact 指 向 当前 


location 对 应 的 


ngx http core loc conf 七 结构 体 ， 否 则 使 用 





inclusive 指 向 该 结构 体 ， 且 


exact 的 优先 级 高 于 


inclusive */ 


clcf = 1q->exact 1q->exact : 1q->inclusive; /*clcf->loc conf 这 个 指针 数组 里 保存 着 当前 
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location 下 所 有 


HTTP 模 块 使 用 


create loc conf 方 法 生成 的 结构 体 的 指针 


4 
ctx->loc conf = clcf->loc conf; // 调用 
merge loc conf 方 法 合并 
SLV、 
loc 级 别 配 置 项 
rv = module->merge loc conf(cf, loc conf[ctx index], clcf->loc conf[ctx index]); /* 注 意 ， 因 为 








location{} 中 可 以 继续 谱 套 


location{} 配 置 块 ， 所 以 是 可 以 继续 合并 的 。 在 


10.1 节 的 例子 中 没有 
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Location 座 套 ， 


10.2.3 节 的 例子 是 体现 出 嵌 套 关系 的 ， 可 以 对 照 着 图 


10-5 来 理解 


* 


rv = ngx http merge locations(cf, clcf->locations, clcf->loc conf, module, ctx index); } 


*ctx = saved; 


return NGX CONF OK; 





在 针对 每 个 HTTP 模 块 循环 调用 ngx http merge _Sservers 方 法 后 ， 就 可 以 完成 所 有 的 合并 配 
置 项 工作 了 。 
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10.3 ”监听 端口 的 管理 


监听 端口 属于 server 虚 拟 主机 ， 它 是 由 server 介 块 下 的 listen 配 置 项 决定 的 。 同 时 ， 它 与 
server 们 块 对 应 的 ngx_http_core_srv_conf t 结 构 体 密切 相关 ， 本 节 将 介绍 这 两 者 间 的 关系 ， 以 
及 监听 端口 的 数据 结构 。 


每 监听 一 个 TICP 端 口 ， 都 将 使 用 一 个 独立 的 ngx_http_conf port 结构 体 来 表示 ， 如 下 所 





typedef struct { 


// socket 地 址 家 族 


ngx int t family; 


// 监听 端口 


in port t port; 


// 监听 的 端口 下 对 应 着 的 所 有 


ngx http conf addr 七 地 址 





ngx array t addrs; 
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这 个 保存 着 监听 端口 的 ngx_http_conf port t 将 由 全 局 的 ngx_http_core_main conf t 结 构 体 
保存 。 下 面 再 来 看 一 下 ports 容 器 ， 如 下 所 示 。 





typedef struct { 


// 存放 着 该 


http{} 配 置 块 下 监听 的 所 有 


ngx http conf port 七 端口 





ngx array t *ports; 


} ngx http core main conf t; 








在 前 面 的 代码 中 ，ngx_http_ conf port t 的 addrs 动 态 数 组 可 能 不 太 容 易 理 解 。 可 先 回顾 一 
下 listen 配 置 项 的 语法 ， 在 10.1 贡 的 例子 中 ， 对 同一 个 端口 8000， 我 们 可 以 同时 监听 
127.0.0.1:8000、173.39.160.51:8000 这 两 个 地 址 ， 当 一 台 物 理 机 器 具备 多 个 下 地 址 时 这 是 很 有 
用 的 。 有 具体 到 HTTP 框 架 的 实现 上 ，Nginx 是 使 用 ngx_http_conf addr t 结 构 体 来 表示 一 个 对 应 
着 具体 地 址 的 监听 端口 的 ， 因 此 ， 一 个 ngx_http_conf port 多 会 对 应 多 个 
ngx_http conf addr t， 而 ngx_http conf addr tt 就 是 以 动态 数组 的 形式 保存 在 addrs 成 员 中 的 。 
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下 面 再 来 看 看 ngx http_conf addr t 的 定义 ， 如 下 所 示 。 





typedef struct { 


// 监听 套 接 字 的 各 种 属性 


ngx http listen opt t opt; 





/* 六 下 


3 个 散 列表 用 于 加 速 寻找 到 对 应 监听 端口 上 的 新 连接 ， 确 定 到 底 使 用 哪个 


server{} 虚 拟 主机 下 的 配置 来 处 理 它 。 所 以 ， 散 列表 的 值 就 是 


ngx http core srv conf 七 结构 体 的 地 址 





4 


// 完全 匹配 


server name 的 散 列 表 


ngx hash t hash; 
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ngx hash wildcard t *wc head; 


// 通配符 后 置 的 散 列 表 


ngx hash wildcard 七 *wc tail; 


#if (NGX PCRE 





// 下 面 的 


regex 数 组 中 元 素 的 个 数 


ngx uint t nregex; 


/*regex 指 向 静态 数组 ， 其 数组 成 员 就 是 


ngx http server name 七 结构 体 ， 表 示 正 则 表达 式 及 其 匹配 的 





server{} 虚 拟 主机 


*/ 


ngx http server name t *regex; #endif 








// 该 监听 端口 下 对 应 的 默认 


SEerV 
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ngx _ http core srv conf 七 *default server; // servers 动 态 数 组 中 的 成 员 将 指向 





ngx http core srv conf 七 结构 体 





ngx array t servers; 


} ngx http. conf addr t; 








在 上 面 的 servers 动 态 数 组 中 ， 保 存 的 数据 类 型 是 ngx_http_core_srv_conf t**， 人 简单 来 说 ， 
就 是 由 servers 数 组 把 监听 的 端口 与 server 人 虚拟 主机 关联 起 来 了 。 图 10-9 展 示 了 10.1 节 的 例子 
中 监听 端口 与 server 人 虚拟 主机 间 在 内 存 中 的 关系 。 
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ngx_http _conf_port tt 


+family 










addrs 


ngx_http_core_main_conf_t 








监听 端口 8000 





+ we_head 
+ we_tail 
+ default _ server 


73.39.160.51: 8000 


*.80 | 1270 0.1. 8000 


SC 一 ngx_http _core _loc _conf _+ 






server A 配置 块 下 的 





| ”| -| server B 配置 块 下 的 


ngx_http _ core _loc _conf _t 
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图 10-9 ”监听 端口 与 server{} 虚 拟 主机 间 的 关系 


下 面 来 解释 一 下 图 10-9。 整 个 htp 仓 块 下 共 监 听 了 3 个 端口 ， 分 别 是 80、8000、8080， 
此 ，ngx_http_core_main conf t 中 的 ports 动 态 数 组 有 3 个 ngx_http_conf port t 成 员 存放 这 3 个 站 
口 。 除 了 8000 端 口 对 应 了 两 个 ngx http_conf addr t 结 构 体 外 “(分别 是 127.0.0.1:8000 和 
173.39.160.51:8000) ，80 和 8080 都 相当 于 默认 监听 了 该 端口 下 的 所 有 地 址 (实际 上 ，listen 
80 就 相当 于 listen*.80) ， 因 此 ， 这 两 个 端口 各 自 对 应 了 一 个 ngx_http_conf addr t 结 构 体 。 
个 监听 地 址 ngx_http_conf addr t 的 servers 动 态 数 组 中 关联 着 监 昕 地 址 对 应 的 server 人 {虚拟 主 
机 ， 根 据 10.1 节 的 例子 可 以 知道 ，server A 配置 块 对 应 着 监听 地 址 *.80 和 127.0.0.1:8000， 而 
server B 配 置 块 对 应 着 监听 地 址 *.80、*.8080 和 173.39.160.51:8000。 





对 于 每 一 个 监听 地 址 ngx_ http_conf addr t， 都 会 有 8.3.1 节 中 介绍 过 的 ngx listening 与 其 
相对 应 ， 而 ngx _ listening t 的 handler 回 调 方法 设置 为 ngx http init connection， 所 以 ， 新 的 TCP 
连接 成 功 建 立 后 都 会 调用 ngx_http_init connection 方 法 初始 化 HTTP 相关 的 信息 ， 第 11 章 将 会 
详细 介绍 ngx http_init connection 方 法 的 实现 。 
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10.4 ”server 的 快速 检索 


在 10.2.2 市 中 可 以 看 到 ， 每 一 个 虚拟 主机 server{} 配 置 块 都 由 一 个 
ngx_http_core_srv_conf t 结 构 体 来 标识 ， 这 些 ngx_http_core_srv_conf { 又 是 通过 全 局 的 
ngx_http_core_main_conf t 结 构 中 的 servers 动 态 数组 关联 起 来 的 。 这 意味 着 当 开 始 处 理 一 个 
HTTP 新 连接 时 ， 接 收 到 HTTP 头 部 并 取 到 Host 后 ， 需 要 遍历 ngx http core main conf t 的 
servers 数 组 才能 找到 与 server name 配 置 项 匹配 的 虚拟 主机 配置 块 ， 这 样 的 时 间 复 杂 度 显然 是 
不 可 接受 的 ， 因 为 当 nginx.conf 配 置 文件 中 拥有 数 以 百 计 的 server{} 块 时 ， 碍 询 效率 就 太 低 
了 。 于 是 ，HTTP 框 架 使 用 了 第 7 章 中 介绍 过 的 散 列 表 来 存放 虚拟 主机 ， 其 中 每 个 元 素 的 关键 


字 是 server name 字 符 串 ， 而 值 则 是 ngx http core srv_conf tt 结构 体 的 指针 。 











在 10.3 节 中 介绍 过 ， 负 责 监 听 一 个 端口 地 址 的 ngx_http_conf addr tt 结构 体 拥有 下 面 3 个 成 
: hash、wc_head、wec tail， 这 3 个 成 员 对 应 着 7.7.3 节 中 介绍 过 的 带 通配符 的 散 列 表 。 这 个 
配 符 的 散 列 表 的 使 用 方法 〈 包 括 如 何 构造 、 检 索 ) 在 7.7 节 中 已 详细 描述 过 ， 这 里 不 再 








3 





开 者 
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10.5 _ location 的 快速 检索 





从 10.2.3 节 中 可 以 了 解 到 ， 每 一 个 server 块 可 以 对 应 着 多 个 location 块 ， 而 一 个 location 块 
还 可 以 继续 符 套 多 个 location 块 。 每 一 批 1ocation 块 是 通过 双向 链表 与 它 的 父 配置 块 〈 要 么 属 
于 server 块 ， 要 么 属于 location 块 关联 起 来 的 。 由 双向 链表 的 查询 效率 可 以 知道 ， 当 一 个 请 
求 根据 10.4 节 中 描述 过 的 散 列 表 快 速 查询 到 server 块 时 ， 必 须 遍 历 其 下 的 所 有 location 组 成 的 
双向 链表 才能 找到 与 其 URI 孢 配 的 location 配 置 块 ， 这 也 是 用 户 无 法 接受 的 。 下 面 看 看 HTTP 
框架 又 是 怎样 通过 静态 的 二 又 查 找 树 来 保存 location 的 。 























// cmcf 就 是 该 


http 块 下 全 局 的 


ngx http core main conf 七 结构 体 





cmcf = ctx->main conf[ngx http core module.ctx index]; /*cscfp 指 向 保存 所 有 


ngx http core srv conf 七 结构 体 指针 的 





servers 动 态 数 组 的 第 


1 个 元 素 


cscfp = cmcf->servers.elts; 


http 块 下 的 所 有 


server 块 
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for (s = 0; s < cmcf->servers.nelts; s++) 1{ 


/*clcf 是 


server 块 下 的 


ngx http core loc conf 结构 体 ， 





locations 成 员 以 双向 链表 关联 着 隶属 于 这 个 


server 块 的 所 有 


location 块 对 应 的 


ngx http core loc conf 结构 体 





类 


clcf = cscfp[s]->ctx->loc conf[ngx http _ core module.ctx index]; /* 将 


ngx http core loc conf 七 组 成 的 双向 链表 按照 





location 匹配 字符 串 进 行 排序 。 注 意 : 这 个 操作 是 递归 进行 的 ， 如 果菜 个 


Location 块 下 还 具有 其 他 


Location， 那 么 它 的 


locations 链 表 也 会 被 排序 


发/ 


if (ngx http init locations(cf, cscfpls], cilcf) != NGX OK) { 





return NGX CONF ERROR; 
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/* 根 据 已 经 按照 


Location 字符 串 排 序 过 的 双向 链表 ， 快 速 地 构建 静态 的 二 又 查找 树 。 与 


ngx http init Locations 方 法 类 似 ， 这 个 操作 也 是 递归 进行 的 


人 


if (ngx http init static location trees(cf, clcf) != NGX OR) { 





return NGX CONF ERROR; 








注意 ， 这 里 的 二 又 碍 找 树 并 不 是 第 7 音 中 介绍 过 的 红 黑 树 ， 不 过 ， 为 什么 不 使 用 红 黑 树 
呢 ? 因为 location 是 由 nginx.conf 中 读 取 到 的 ， 它 是 静态 不 变 的 ， 不 存在 运行 过 程 中 在 树 中 添 
加 或 者 删除 location 的 场景 ， 而 且 红 黑 树 的 查询 效率 也 没有 重新 构造 的 静态 的 完全 平衡 二 又 
树 高 。 











这 棵 静态 的 二 又 平衡 查找 树 是 用 ngx http_ location tree node t 结 构 体 来 表示 的 ， 如 下 所 





typedef struct ngx http location tree node s ngx http location tree node t; struct ngx http location tree node 





// 左 子 树 


ngx http Location tree node t *]eft; // 右 子 树 
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ngx http location tree node 七  *right; // 无 法 完全 匹配 的 


location 组 成 的 树 


ngx http location tree node t *tree; /* 如 果 


location 对 应 的 


URI 匹 配 字符 串 属 于 能 够 完全 匹配 的 类 型 ， 则 


exact 指 向 其 对 应 的 


ngx http core loc conf 结构 体 ， 否 则 为 





NULL 空 指针 


*/ 


ngx http core loc conf 七 *exact; 





/* 如 果 


location 对 应 的 


URI 匹 配 字符 串 属 于 无 法 完全 匹配 的 类 型 ， 则 


inclusive 指 向 其 对 应 的 


ngx http core loc conf 七 结构 体 ， 否 则 为 





NUILL 空 指针 


发/ 





ngx http core loc conf 七 *inclusive; // 自动 重 定向 标志 
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u char auto redirect; 


// name 字 符 事 的 实际 长 度 


u char len; 


// name 指 向 


location 对 应 的 


URI 匹 配 表 达 式 


u char name[1]; 





HTTP 框 架 在 ngx http core_ module 模 块 中 定义 了 ngx http core find location 方 法 ， 用 于 从 
静态 二 又 查找 树 中 快速 检索 到 ngx http core loc_conf t 结 构 体 ， 这 在 第 11 章 探讨 HTTP 请 求 的 
处 理 过 程 时 将 会 倍 到 。 
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10.6 _ HTTP 请 求 的 11 个 处 理 阶 段 


Nginx 为 什么 要 把 HTTP 请 求 的 处 理 过 程 分 为 多 个 阶段 呢 ?” 这 要 从 第 8 章 介 绍 过 的 “一 切 丝 
模块 ”说 起 。Nginx 的 模块 化 设计 使 得 每 一 个 HTTP 模 块 可 以 仅 专 注 于 完成 一 个 独立 的 、 简 单 
的 功能 ， 而 一 个 请 求 的 完整 处 理 过 程 可 以 由 无 数 个 HTTP 模 块 共同 合作 完成 。 这 种 设计 有 非 
常 好 的 简单 性 、 可 测试 性 、 可 扩展 性 ， 然 而 ， 当 多 个 HITTP 模 块 流水 式 地 处 理 同 一 个 请 求 
时 ， 单 一 的 处 理 顺 序 是 无 法 满足 灵活 性 需求 的 ， 每 一 个 正在 处 理 请 求 的 HTTP 模块 很 难 灵 
活 、 有 效 地 指定 下 一 个 HTTP 处 理 模 块 是 哪 一 个 。 而 且 ， 不 划分 处 理 阶段 也 会 让 HTTP 请 求 的 
完整 处 理 流程 难以 管理 ， 每 一 个 HTTP 模 块 也 很 难 正确 地 将 自己 插入 到 完整 流程 中 的 合适 位 
置 中 。 


因此 ，HTTP 框 架 依据 常见 的 处 理 流程 将 处 理 阶段 划分 为 11 个 阶段 ， 其 中 每 个 处 理 阶 段 
都 可 以 由 任意 多 个 HTTP 模 块 流 水 式 地 处 理 请 求 。 先 来 回顾 一 下 第 3 章 中 曾经 提 到 过 的 
ngx_http_phases 阶 段 的 定义 ， 如 下 所 示 。 


typedef enum { 


// 在 接收 到 完整 的 


HTTP 头 部 后 处 理 的 


HTTP 阶 段 





NGX HTTP POST READ PHASE = 0， 








下 证 六 各 站 由 有 由 有 由 http:/ /ww linuxorobe. con 





URI 与 


location 表 达 式 匹配 前 ， 修 改 请 求 的 


URI (所 谓 的 重 定向 ) 是 一 个 独立 的 


HTTP 阶 段 


*/ 





NGX HTTP SERVER REWRITE PHASE, 




















/* 根 据 请 求 的 


URI 寻 找 匹 配 的 


location 表达 式 ， 这 个 阶段 只 能 由 


ngx_http_core moqule 模 块 实现 ， 不 建议 其 他 


HTTP 模 块 重新 定义 这 一 阶段 的 行为 





下 PT DDD http:// ww |i nuxprobe. con 





/* 在 


NGX HTTP FIND CONFIG PHASE 阶 段 寻 找到 匹配 的 








location 之 后 再 修改 请 求 的 


URI*/ 





NGX HTTP REWRITE PHASE, 














/* 这 一 阶段 是 用 于 在 





Dd) 
功 


rewrite 重 
URL 后 ， 防 止 错误 的 

nginx.conf 配 置 导 致死 循环 (递归 地 修改 

URI) ， 因 此 ， 这 一 阶段 仅 由 
ngx_http_core_module 模 块 处 理 。 目 前 ， 控 制 死 循环 的 方式 很 简单 ， 首 先 检 查 


一 用 门下 三 


站 中 HH Ptto: /wwvllinuxorobe, con 





Da 
可 


10 次 重 人 





/就 认为 进入 了 


rewrite 死 循环 ， 这 时 在 








NGX HTTP POST REWRITE PHASE 阶 段 就 会 向 用 户 返 回 











500， 表 示 服 务 器 内 部 错误 























4 
NGX_ HTTP POST REWRITE PHASE, 
/* 表 示 在 处 理 
NGX_HTTP_ACCESS_PHASE 阶 段 决定 请 求 的 访问 权限 前 ， 
HTTP 模 块 可 以 介入 的 处 理 阶 段 
二 





NGX HTTP PREACCESS _ PHASE 














~ 


// 这 个 阶段 用 于 让 
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HTTP 模 块 判断 是 否 允 许 这 个 请 求 访问 


Nginx 服 务 器 


NGX HTTP ACCESS PHASE， 








/* 在 


NGX_HTTP_ACCESS_PHASE 阶 段 中 ， 当 








HTTP 模 块 的 


handler 处 理 函 数 返 回 不 允许 访问 的 错误 码 时 (实际 就 是 


NGX_HTTP_ FORBIDDEN 或 者 





NGX_HTTP_UNAUTHORIZED) ， 这 里 将 负责 向 用 户 发 送 拒绝 服务 的 错误 响应 。 因 此 ， 这 个 阶段 实际 上 用 于 给 





NGX_HTTP ACCESS_ PHASE 阶段 收尾 








Sy 








NGX HTTP POST ACCESS PHASE 
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~ 








/* 这 个 阶段 完全 


是 为 


try_files 配 置 项 而 设立 的 ， 当 


HTTP 请 求 访问 静态 文件 资源 时 ， 


try_files 配 置 项 可 以 使 这 个 请 求 顺序 地 访问 多 个 静态 文件 资源 ， 如 果 茶 一 次 访问 失败 ， 则 继续 访问 


try_files 中 指定 的 下 一 个 静 














NGX HTTP TRY FIL 


ES PHASE 阶 段 中 实现 的 





NGX HTTP TRY 


FILES PHASE, 











// 用 于 处 理 


HTTP 请 求 内 容 的 阶段 


HTTP 模 块 最 愿意 介入 


NGX HTTP CONTENT PHASE 


， 这 是 大 部 分 


的 阶段 





卫 





~ 





的 阶段 。 例 如 ， 


[| 站 http:/ /Ww |1 nNUxorobe. con 





ngx http log module 模块 就 在 这 个 阶段 中 加 入 了 一 个 


handler 处 理 方 法 ， 使 得 每 个 


HTTP 请 求 处 理 完毕 后 会 记录 


access 1og 访 问 日 志 


2 





NGX HTTP LOG PHASE 


} ngx http phases; 





对 于 这 11 个 处 理 阶 段 ， 有 些 阶 段 是 必 备 的 ， 有 些 阶段 是 可 选 的 ， 当 然 也 可 以 有 多 个 
HTTP 模 块 同时 介入 同一 阶段 ‘这 时 ， 将 会 在 一 个 阶段 中 按照 这 些 HTTP 模 块 的 ctx_index 顺 序 
来 依次 执行 它们 提供 的 handler 处 理 方法 ) 。 在 10.6.1 节 中 将 会 介绍 这 11 个 阶段 共同 适用 的 规 
则 ， 在 10.6.2 节 ~10.6.12 节 则 会 描述 这 些 具体 的 处 理 阶段 。 


@@ ij 总 ng http_phases 定 义 的 11 个 阶段 是 有 顺序 的 ， 必 须 按照 其 定义 的 顺序 执行 。 同 
时 也 要 意识 到 ， 并 不 是 说 一 个 用 户 请 求 最 多 只 能 经 过 11 个 HTTP 模 块 提供 的 
ngx_http_handler_pt 方 法 来 处 理 ,，NGX_HTTIP_POST_READ_PHASE、 
NGX_HTIP SERVER_ REWRITE PHASE NGX HTIP REWRITE PHASE. 
NGX_ HTIP PREACCESS PHASE NGX HTIP ACCESS_ PHASE. 


NGX_HTTP_ CONTENT PHASE、NGX_HTTP_LOG PHASE 这 7 个 阶段 可 以 包括 任意 多 个 处 
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理 方法 ， 它 们 是 可 以 同时 作用 于 同一 个 用 户 请 求 的 。 而 
NGX_HTTP_FIND_CONFIG_PHASE、NGX_HTTP POST REWRITE_PHASE. 
NGX_HTTP POST _ ACCESS_PHASE、NGX_HTTP TRY FILES PHASE 这 4 个 阶段 则 不 允许 


HTTP 模 块 加 入 自己 的 ngx_http_handler_pbt 方 法 处 理 用 户 请 求 ， 它 们 仅 由 HTTP 框架 实现 。 


10.6.1 _ HITP 处 理 阶 段 的 普 适 规则 


下 面 先 来 看 看 HTTP 阶 段 的 定义 ， 它 包括 checker 检 查 方法 和 handler 处 理 方法 ， 如 下 所 





typedef struct ngx http phase handler s ngx http phase handler t; /xx 一 个 





HTTP 处 理 阶 段 中 的 
checker 检 查 方法 ， 仅 可 以 由 
HTTP 框 架 实 现 ， 以 此 控制 
HTTP 请 求 的 处 理 流程 
*/ 


typedef ngx int 七 (*ngx http phase handler pt) (ngx http request t r, ngx http phase handler t ph); /* 由 


HTTP 模 块 实现 的 
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handler 处 理 方 法 ， 这 个 方法 在 第 


ngx http mytest handler 方 法 实现 过 
4 


typedef ngx int t (*ngx http handler pt) (ngx http request t *r); // 注意 : 


ngx_http_phase_handler 七 结构 体 仅 表示 处 理 阶 段 中 的 一 个 处 理 方法 


struct ngx http phase handler s { 


/* 在 处 理 到 菜 一 个 


HTTP 阶 段 时 ， 


HTTP 框 架 将 会 在 


checker 方 法 已 实现 的 前 提 下 首先 调用 


checker 方 法 来 处 理 请 求 ， 而 不 会 直接 调用 任何 阶段 中 的 
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handler 方 法 ， 只 有 在 


checker 方 法 中 才 会 去 调用 


handler 方 法 。 因 此 ， 事 实 上 所 有 的 





checker 方 法 都 是 由 框架 中 的 


ngx_ http core module 模 块 实现 的 ， 且 普通 的 


HTTP 模 块 无 法 重 定义 





checker 方 法 
*/ 


ngx _ http Phase handler pt checker; 


ngx_ http core module 模 块 以 外 的 
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handqler 方 法 才能 介入 某 一 个 


HTTP 处 理 阶段 以 处 理 请 求 


* 


ngx http handler pt handler; 


// 将 要 执行 的 下 一 个 


HTTP 处 理 阶 段 的 序号 


/* next 的 设计 使 得 处 理 阶段 不 必 按 顺序 依次 执行 ， 既 可 以 向 后 跳跃 数 个 阶段 继续 执行， 也 可 以 跳跃 到 之 前 曾经 执行 过 的 某 个 阶段 重新 执行 。 





next 表 示 下 一 个 处 理 阶段 中 的 第 


二 


ngx_http _ phase handler 七 处 理 方法 


4 


ngx uint t next; 


D'// WN TT AUXOr OBE. coOn 





@ 注意 ”通常 ， 在 任意 一 个 ngx_http_phases 阶 段 ， 都 可 以 拥有 零 个 或 多 个 
ngx_http_phase_handler_t 结 构 体 ， 其 含义 更 接近 于 茶 个 HTTIP 模 块 的 处 理 方法 。 


一 个 http 们 块 解析 完毕 后 将 会 根据 nginx.conf 中 的 配置 产生 由 ngx_http phase_handler { 组 成 
的 数组 ， 在 处 理 HTTP 请 求 时 ， 一 般 情况 下 这 些 阶段 是 顺序 向 后 执行 的 ， 但 
ngx_http phase_handler t 中 的 next 成 员 使 得 它们 也 可 以 非 顺 序 执行 。ngx_http_phase_engine t 结 
构 体 就 是 所 有 ngx http phase handler t 组 成 的 数组 ， 如 下 所 示 。 








typedef struct { 


/*handlers 是 由 


ngx http phase handler 二 构成 的 数组 首 地 址 ， 它 表示 一 个 请 求 可 能 经 历 的 所 有 


ngx_http handler pt 处 理 方 法 


4 


ngx http phase handler t *handlers; 


/* 表 示 











NGX_HTTP_SERVER REWRITE _ PHASE 阶段 第 














1 


ngx_http phase handler 七 处 理 方法 在 
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handlers 数 组 中 的 序号 ， 用 于 在 执行 


HTTP 请 求 的 任何 阶段 中 快速 跳 转 到 





NGX_HTTP SERVER REWRITE PHASE 阶 段 处 理 请 求 




















*/ 





ngx uint t server rewrite index; 


/* 表 示 





NGX_HTTP REWRITE _PHASE 阶 段 第 














人 


ngx_http phase handler 七 处 理 方 法 在 


handlers 数 组 中 的 序号 ， 用 于 在 执行 


HTTP 请 求 的 任何 阶段 中 快速 跳 转 到 

















NGX_HTTP_RENWRITE _ PHASE 阶段 处 理 请 求 
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ngx uint t location rewrite index; 


} ngx http phase engine t; 








可 以 看 到 ，ngx_http_phase_engine t 中 保存 了 在 当前 nginx.con 人 配置 下 ， 一 个 用 户 请 求 可 能 
经 历 的 所 有 ngx_http_ handler pt 处 理 方 法 ， 这 是 所 有 HTTP 模 块 可 以 合作 处 理 用 户 请 求 的 关 
键 ! 这 个 ngx_http_ phase engine t 结 构 体 是 保存 在 全 局 的 ngx_http_core_main_conf tt 结构 体 中 
的 ， 如 下 所 示 。 








typedef struct { 


/* 由 下 面 各 阶段 处 理 方法 构成 的 


phases 数 组 构建 的 阶段 引擎 才 是 流水 式 处 理 


HTTP 请 求 的 实际 数据 结构 


my 


ngx http phase engine t phase engine; 





/用 于 在 


HTTP 框 架 初 始 化 时 帮助 各 个 


HTTP 模 块 在 任意 阶段 中 添加 
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HTTP 处 理 方 法 ， 它 是 一 个 有 


11 个 成 员 的 


ngx http phase t 数 组， 其 中 每 一 个 


ngx_http phase tt 结构 体 对 应 一 个 


HTTP 阶 段 。 在 


HTTP 框 架 初始 化 完毕 后 ， 运 行 过 程 中 的 


phases 数 组 是 无 用 的 


*y 





ngx http phase t phases[NGX HTTP LOG PHASE + 1]; … 


} ngx http core main conf t; 








在 ngx_http core main conf t 中 关于 HTTP 阶 段 有 两 个 成 员 : phase engine 和 phases， 其 中 
phase_engine 控 制 运行 过 程 中 一 个 HTTP 请 求 所 要 经 过 的 HTTP 处 理 阶段 ， 它 将 配合 
结 


ngx http request t 结 构 体 中 的 phase handler 成 员 使 用 (phase handler 指 定 了 当前 请 求 应 当 执 行 
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哪 一 个 HTTP 阶 段 ，; 而 phases 数 组 更 像 一 个 临时 变量 ， 它 实际 上 仪 会 在 Nginx 启 动 过 程 中 用 
到 ， 它 的 唯一 使 命 是 按照 11 个 阶段 的 概念 初始 化 phase_engine 中 的 handlers 数 组 。 下 面 看 一 下 
ngx http phase t 的 定义 。 





typedef struct { 


// handlers 动 态 数组 保存 着 每 一 个 


HTTP 模 块 初 始 化 时 添加 到 当前 阶段 的 处 理 方 法 


ngx array t handlers; 


} ngx http phase t; 





在 HTTP 框 架 的 初始 化 过 程 中 ， 任 何 HTTP 模 块 都 可 以 在 ngx http module t 接 口 的 
postconfiguration 方 法 中 将 自 定义 的 方法 添加 到 handler 动 态 数组 中 ， 这 样 ， 这 个 方法 就 会 最 
添加 到 phase_engine 中 注意， 第 3 章 中 mytest 模 块 并 没有 把 ngx_http_mytest_handler 方 法 加 入 到 
phases 的 handlers 数 组 中 ， 这 是 因为 对 于 NGX HTTP CONTENT _ PHASE 阶段 来 说 ， 还 有 另 一 
种 初始 化 方法 ， 在 10.6.11 节 中 我 们 会 介绍 ) 。 在 第 11 章 中 可 以 看 到 这 些 HTTP 阶 段 是 如 何 执 











下 面 将 会 简要 介绍 这 11 个 HTTP 处 理 阶 段 ， 读 者 关注 重点 是 每 个 阶段 的 checker 方 法 都 做 
了 些 什么 。 


10.6.2 NGX HTTP POST READ PHASE 阶段 


当 HTTP 框 架 在 建立 的 TCP 连 接 上 i 户 发 送 的 完整 HTTP 请 求 头 部 时 ， 开 始 执行 
中 NNDDNDTD TD bs con 





NGX HTTP POST READ PHASE 阶段 的 checker 方 法 。 下 面 先 来 看 看 它 的 checker 方 法 
ngx_http_core_generic_ phase， 这 是 一 个 很 典型 的 checker 方 法 ， 下 面 就 给 出 相关 代码 ， 以 便 读 
者 对 checker 方 法 的 执行 过 程 有 个 直观 认识 。 








ngx int t ngx http core generic Phase (ngx http request t r, ngx http phase handler t ph) { 


// 调用 这 一 阶段 中 各 


HTTP 模 块 添加 的 


handler 处 理 方法 


ngx int t rc = ph->handler (r); 


/* 如 果 


handler 方 法 返回 


NGX_OK， 之 后 将 进入 下 一 个 阶段 处 理 ， 而 不 会 理会 当前 阶段 中 是 否 还 有 其 他 的 处 理 方法 


4 


if (EG == NGX OK) A 


r->phase handler = ph->next; 





return NGX AGAIN; 
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/* 如 果 


handler 方 法 返回 


NGX_D 








RECLINE 








NGX_OK 与 


NGX_D 








ECLIN 





ED 之 间 的 区 别 





if (rc 


/ 














== NGX DECLINED) { 


r->phase handlertt+; 


return NGX AGAIN; 


* 如 果 


handler 方 法 返回 


NGX _AGAIN 或 者 


Nem so 





,4 万 全 于 者 一个 半 到 加 业 站 | 





D， 那 么 将 进入 下 一 个 处 理 方法 ， 这 个 处 理 方法 既 可 能 属于 当前 阶段 ， 也 可 能 属于 下 一 个 阶段 。 注 意 返 回 


*y 


htt po: // WW | 1 Nuxpor obe. con 


*/ 


if (rc == NGX AGAIN || rc == NGX DONE) { 





return NGX OR; 


/* 如 果 


handler 方 法 返回 


NGX_ERROR 或 者 类 似 





NGX_HTTP_ 开 头 的 返回 码 ， 则 调用 


ngx http finalize request 结 束 请 求 


4 


ngx http finalize request(r, rc); 


return NGX OK; 





任意 HTTP 模 块 需要 在 NGX HTTP POST READ PHASE 阶 段 处 理 HTTP 请 求 时 ， 必 须 首 
先 在 ngx_http core main conf 结构 体 中 的 phases[NGX HTTP POST READ PHASE] 动 态 数组 


中 添加 目 己 实现 的 ngx_http_handler pt 方法 。 在 此 阶段 中 ，ngx_http_ handler pt 方法 的 返回 值 可 
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以 产生 4 种 不 同 的 影响 ， 总 结 见 表 10-1。 


表 10-1 NGX_HTTP POST READ_PHASE、NGX_HTTP PREACCESS_PHASE、 


NGX_HTIP_LOG_PHASE 阶 段 THTTP 模 块 的 ngx_http_handler_pt 方 法 返回 值 意义 





返回 值 意 义 
执行 下 一 个 ngx_http_phases 阶段 中 的 第 一 个 ngx_http_handler_pt 处 理 方法 。 这 意味 着 两 
ee 点 : 中 即使 当前 阶段 中 后 续 还 有 一 些 HTTP 模块 设置 了 ngx_http_ handler pt 处 理 方法 ， 返 回 
2 NGX OK 之 后 它们 也 是 得 不 到 执行 机 会 的 ; 四 如 果 下 一 个 ngx_http_ phases 阶段 中 没有 任何 
HTTP 模块 设置 了 ngx_http_ handler pt 处 理 方法 ,将 再 次 寻找 之 后 的 阶段 ， 如 此 循环 下 去 
( 续 ) 
返回 值 意 义 


按照 顺序 执行 下 一 个 ngx_http handler pt 处 理 方法 。 这 个 顺序 就 是 ngx_http_phase_ 
engine t 中 所 有 ngx_http phase handler t 结构 体 组 成 的 数组 的 顺序 
NGX AGAIN 当前 的 ngx_http_handler_pt 处 理 方 法 尚未 结束 ， 这 意味 着 该 处 理 方 法 在 当前 阶段 有 机 会 再 
次 被 调用 。 这 时 一 般 会 把 控制 权 交还 给 事件 模块 ， 当 下 次 可 写 事 件 发 生 时 会 再 次 执行 到 该 


NGX DECLINED 





NGX DONE i 

a ngx_http_handler_pt 处 理 方法 
NGX ERROR A bo a 
他 二 需要 调用 ngx_http_finalize_ request 结束 请 求 
Se ] 


目前 ， 官 方 的 ngx_http realip_ module 模块 是 从 NGX_HTTP POST _ READ PHASE 阶段 介 
入 以 处 理 HTTP 请 求 的 ， 它 在 postconfiguration 方 法 中 是 这 样 将 自 定义 的 ngx_http_handler_pt 处 
理 方 法 添加 到 HTTP 框架 中 的 ， 如 下 上 所 示 。 





ngx http realip _ init 方法 实际 上 就 是 


Postconfiguration 接 口 的 实现 


0 





ngx http handler pt *h; 


// 首先 获取 到 全 局 的 


ngx http core main conf 七 结构 体 





ngx http core main Conf 七 *cmcf 





11 个 成 员 ， 取 出 


NGX HTTP POST R 











EAD PHASE 阶 段 的 


handlers 动 态 数 组 ， 向 其 中 添加 


ngx_http handler pt 处 理 方法 ， 这 样 


ngx http realip module 模 块 就 介入 


HTTP 请 求 的 


NGX HTTP POST R 








EAD PHASI 





EE 处 理 阶 段 了 


ngx http conf get module main conf( cf, ngx http core module); /*phases 数 
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人 








h = ngx array Push(&cmcf->phases [NGX HTTP POST READ PHASE] .handlers); if (h == NULIL) ({ 





return NGX ERROR; 





/* ngx http realip handler 方 法 就 是 实现 了 


ngx_http handler pt 接口 的 方法 


4 


*h = ngx http realip handler; 


/* 实 际 上 ， 同 一 个 


HTTP 模 块 的 同一 个 


ngx_http_realip_handler 方 法 ， 完 全 可 以 设置 到 两 个 不 同 的 阶段 中 的 。 例 如 ， 





phases[NGX HTTP PREACCESS PHASE.handlers] 动 态 数组 中 也 添加 了 














ngx http realip handler 方 法 


4 





h = ngx array push(&cmcf->phases[NGX HTTP PREACCESS PHASE] .handlers); if (hn == NULL) ({ 

















return NGX ERROR; 
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/*ngx http realip handler 处 理 方 法 同时 介入 了 


NGX HTTP POST READ PHASE、 














NGX HTTP PREACCESS PHASE 这 两 个 














HTTP 处 理 阶 段 


*h = ngx http realip handler; 


return NGX OK; 





通过 这 个 例子 可 以 看 到 怎样 在 NGX HTTP POST READ PHASE 或 者 
NGX HTTP PREACCESS PHASE 阶 段 添 加 HTTP 模 块 。 


10.6.3 NGX HTTP SERVER _ REWRITE PHASE 阶 段 


NGX HTTP SERVER_ REWRITE PHASE 阶 段 的 checker 方 法 是 
ngx_http_core_Tewrite_phase。 表 10-2 总 结 了 该 阶段 ngx_http_handler_ pt 处理 方法 的 返回 值 是 
如 何 影响 HTTP 框架 执行 的 ， 注 意 ， 这 个 阶段 中 不 存在 返回 值 可 以 使 请 求 直接 跳 到 下 一 个 阶 
段 执行 。 
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表 10-2 NGX_HTTP SERVER_REWRTITE_ PHASE、NGX_HTTP REWRITE _ PHASE 阶段 下 


HTTP 模 块 的 ngx_http_handler_pt 方 法 返回 值 意义 


涡 


返回 值 汉 兴 
当前 的 ngx_http_ handler_ pt 处理 方法 尚未 结束 ， 这 意味 着 该 处 理 方 法 在 当前 阶段 中 有 机 会 
再 次 被 调用 
当前 ngx_http_handler pt 处 理 方法 执行 完毕 ， 按 照 顺序 执行 下 一 个 ngx_http_handler pt 处 


NGX DONE 


NGX DECLINED 


理 方法 
NGX AGAIN 
NGX DONE Re 当先 i 
需要 调用 ngx_http_finalize_request 结束 请 求 
NGX ERROR 
其 他 


官方 提供 的 ngx http _ rewrite_ module 模 块 定义 了 ngx http rewrite handler 方 法 ， 同 时 将 它 
添加 到 了 NGX_HTTP_SERVER REWRITE PHASE 和 NGX HTTP REWRITE PHASE 阶 段 ， 这 
里 就 不 再 列举 其 代码 了 。 


10.6.4 NGX HTTP FIND CONFIG _ PHASE 阶段 


NGX_HTTP_ FIND_ CONFIG PHASE 是 一 个 关键 阶段 ， 这 个 阶段 是 不 可 以 跳 过 的 ， 也 融 
是 说 ， 在 ngx_http phase_engine t 中 ， 处 理 方 法 组 成 的 数组 必然 要 有 阶段 的 处 理 方 法 ， 因 为 这 
是 HTTP 框 架 基 于 location 设 计 的 基石 。 


HTTP 框 架 提 供 了 ngx http core find config phase 方 法 用 于 执行 这 一 步骤 ， 也 就 是 说 ， 任 
何 HTTP 模 块 不 可 以 向 这 一 阶段 中 添加 处 理 方法 (添加 了 也 是 无 效 
的 ) Ingx http core find config phase 方 法 实际 上 就 是 根据 
NGX _HTTP_ SERVER_REWRITE_ PHASE 步骤 重 写 后 的 URI 检 索 出 匹配 的 location 块 的 ， 其 原 
理 为 从 location 组 成 的 静态 二 又 查找 树 中 快速 检索 ， 有 具体 可 参照 10.5 节 。 


10.6.5 NGX HTTP REWRITE PHASE 阶 段 
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NGX _ HTTP FIND CONFIG _ PHASE 阶段 检索 到 location 后 有 机 会 再 次 利用 rewrite 〈 重 
写 ) URL， 这 一 工作 就 是 在 NGX _ HTTP REWRITE PHASE 阶 段 完 成 的 。 


NGX HTTP REWRITE PHASE 阶 段 与 10.6.3 节 中 的 
NGX _ HTTP SERVER_ REWRITE _ PHASE 阶段 几乎 是 完全 相同 的 ， 它 们 的 checker 方 法 都 是 
ngx_http_core rewrite phase， 在 这 一 阶段 中 ，ngx_http handler pt 方法 的 返回 值 意义 与 表 10-2 
是 完全 相同 的 ， 不 再 壮 述 


10.6.6 NGX HTTP POST REWRITE PHASE 阶 段 


NGX HTTP POST REWRITE PHASE 阶 段 就 像 NGX HTTP FIND CONFIG _ PHASE 阶段 
一 样 ， 只 能 由 HTTP 框 架 实 现 ， 不 允许 HTTP 模 块 癌 该 阶段 添加 ngx_http handler pt 处理 方 法 。 


NGX HTTP POST REWRITE PHASE 阶 段 的 checker 方 法 是 
ngx_http_core_post rewrite phase， 它 的 意义 在 于 检查 rewrite 重 写 URL 的 次 数 不 可 以 超过 10 
次 ， 以 此 防止 由 于 rewrite 死 循环 而 造成 整个 Nginx 服 务 都 不 可 用 。 





10.6.7 NGX HITP PREACCESS _ PHASE 阶段 


NGX_HTTP_PREACCESS_PHASE 阶 段 一 般 用 于 对 当前 请 求 进行 限制 性 处 理 ， 它 的 
checker 方 法 与 10.6.1 节 中 详细 描述 过 的 ngx http core generic phase 方 法 一 样 ， 因 此 ， 在 这 一 
阶段 中 执行 的 ngx_http_handler_ pt 处 理 方 法 ， 其 返回 值 意义 也 与 表 10-1 是 完全 相同 的 ， 不 再 更 


10.6.8 NGX HTTP ACCESS _ PHASE 阶段 


NGX _ HTTP ACCESS _ PHASE 阶段 与 NGX HTTP PREACCESS _ PHASE 阶段 大 不 相同 ， 


人 人 全 全 ei- core pee J [rm Ee 





NGX HTTP ACCESS _ PHASE 阶段 ngx http handler pt 处 理 方法 的 返回 值 有 了 新 的 意义 ， 见 表 
10-3。 


表 10-3 NGX_HTTP_ACCESS_PHASE 阶 段 下 HTTP 模 块 的 ngx_http_handler_pt 方 法 返回 值 意 


义 
返回 值 意 义 
如 果 在 nginx.conf 中 配置 了 satisfy all， 那 么 将 按照 顺序 执行 下 一 个 ngx_ 
NGX OK http handler pt 处 理 方法 ; 如 果 在 nginx.conf 中 配置 了 satisfy any， 那 么 将 热 
行 下 一 个 ngx http re 阶段 中 的 第 一 个 ngx_http_handler_pt 处 理 方法 

NGX DECLINED 按照 顺序 执行 下 一 个 ngx_http_handler pt 处 理 方法 
NGX AGAIN 当前 的 ngx_http_handler_pt 处 理 方法 尚未 结束 ， 这 意味 着 该 处 理 方法 在 当前 
SE 阶段 中 有 机 会 再 次 被 调用 。 这 时 会 把 控制 权 交 还 给 事件 模块 ,下 次 可 写 事 件 

发 生 时 会 再 次 执行 到 该 ngx_http_handler_pt 处 理 方法 
NGX HTTP FORBIDDEN 如 果 在 nginx.conf 中 配置 了 satisfy any， 那 么 将 ngx http request t 中 的 





access code 成 员 设 为 返回 值 ， 按 照 顺序 执行 下 一 个 nagx http_ handler pt 处 
NGX _ HTTP_ UNAUTHORIZED | 理 方法 ; 如 果 在 nginx.conf 中 配置 了 satisfy all， 那 么 调用 ngx_http_finalize 
request 结束 请 求 
NGX ERROR 


生字 需要 调用 ngx_http_finalize_ request 结束 请 求 
是 他 


从 表 10-3 中 可 以 看 出 ，NGX _HTTP ACCESS _ PHASE 阶段 实际 上 与 nginx.conf 杷 置 文件 中 
的 satisfy 配 置 项 有 紧密 的 联系 ， 所 以 ， 任 何 介入 NGX_HTTP_ ACCESS _ PHASE 阶段 的 HTTP 模 
块 ， 在 实现 ngx http_ handler pt 方法 时 都 需要 注意 satisfy 的 参数 ， 该 参数 可 以 由 
ngx_http_core loc_conf t 结 构 体 中 得 到 。 





typedef struct ngx http core loc conf s ngx http core loc conf 七 struct ngx http core loc conf s { 








// 仅 可 以 取 值 为 
NGX HTTP SATISFY ALL 或 者 


NGX HTTP SATISFY ANY 


和 权 于 He 丹 本 由 Ptto: /ww inuxorobe. con 








如 果 不 根据 所 在 location 中 的 satisfy 参 数 来 决定 返回 值 ， 那 么 可 能 造成 未 知 结果 。 
10.6.9 NGX _ HTTP POST ACCESS _ PHASE 阶段 


NGX _ HTTP POST ACCESS _ PHASE 阶段 又 是 一 个 只 能 由 HTTP 框 架 实现 的 阶段 ， 不 人 允 
许 HTTP 模 块 同 该 阶段 添加 ngx http handler pt 处 理 方法 。 这 个 阶段 完全 是 为 之 前 的 
NGX _HTTP_ ACCESS PHASE 阶段 服务 的 ， 换 句 话 说， 如 果 没 有 任何 HITP 模 块 介 入 
NGX _ HTTP ACCESS _ PHASE 阶段 处 理 请 求 ，NGX_HTTP POST ACCESS _ PHASE 阶段 就 不 
会 存在 。 





NGX HTTP POST ACCESS _ PHASE 阶段 的 checker 方 法 是 
ngx_http_core_post_access_phase， 它 的 工作 非常 简单 ， 就 是 检查 ngx_http_request_t 请 求 中 的 
access_code 成 员 ， 当 其 不 为 0 时 融 结 束 请 求 〈 表 示 没 有 访问 权限 ) ， 人 否则 继续 执行 下 一 个 
ngx_http handler pt 处 理 方 法 。 


10.6.10 NGX _ HTTP TRY FILES PHASE 阶段 
NGX_HTTP_TRY _ FILES_PHASE 阶 段 也 是 一 个 只 能 由 HTTP 框 架 实 现 的 阶段 ， 不 允许 
HTTP 模 块 癌 该 阶段 添加 ngx http handler pt 处 理 方法 。 


NGX HTTP TRY FILES _ PHASE 阶段 的 checker 方 法 是 ngx http core try files phase， 它 
是 与 nginx.conf 中 的 try files 配 置 项 密切 相关 的 ， 如 果 try files 后 指定 的 静态 文件 资源 中 有 一 个 
可 以 访问 ， 这 时 就 会 直接 读 取 文件 并 发 送 啊 应 给 用 户 ， 不 会 再 向 下 执行 后 续 的 阶段 ， 如果 所 


口 由 掉 由 有 有 和 所 掉 由 http' /wNv inuxorobe. con 











有 的 静态 文件 资源 都 无 法 执行 ， 将 会 继续 执行 ngx_ http phase_engine t 中 的 下 一 个 
ngx http handler pt 处 理 方法 。 


10.6.11 NGX HTTP CONTENT _ PHASE 阶段 
这 是 一 个 核心 HTTP 阶 段 ， 可 以 说 大 部 分 HTTP 模 块 都 会 在 此 阶段 重新 定义 Nginx 服 务 器 


的 行为 ， 如 第 3 章 中 提 到 的 mytest 模 块 。NGX HTTP CONTENT PHASE 阶 段 之 所 以 被 众多 
HTTP 模 块 “钟爱 *"， 主 要 基于 以 下 两 个 原因 : 











其 一 ， 以 上 9 个 阶段 主要 专注 于 4 件 基础 性 工作 : rewrite 重 写 URL、 找 到 location 配 置 块 、 
判断 请 求 是 否 具备 访问 权限 、try files 功 能 优先 读 取 静态 资源 文件 ， 这 4 个 工作 通常 适用 于 绝 
大 部 分 请 求 ， 因 此 ， 许 多 HTTP 模 块 希 望 可 以 共享 这 9 个 阶段 中 已 经 完成 的 功能 。 





其 二 ，NGX _HTTP_CONTENT_PHASE 阶 段 与 其 他 阶段 都 不 相同 的 是 ， 它 癌 HTTP 模 块 提 
供 了 两 种 介入 该 阶段 的 方式 : 第 一 种 与 其 他 10 个 阶段 一 样 ， 通 过 向 全 局 的 
ngx_http_core_ main_ conf tt 结构 体 的 phases 数 组 中 添加 ngx_http_handler_pt 处 理 方法 来 实现 ， 而 
第 二 种 是 本 阶段 独 有 的 ， 把 希望 处 理 请 求 的 ngx_http_handler pf 方法 设置 到 location 相 关 的 
ngx_http_core_loc_conf t 结 构 体 的 handler 指 针 中 ， 这 正 是 第 3 章 中 mytest 例 子 的 用 法 。 





上 面 所 说 的 第 一 种 方式 ， 也 是 HTTP 模 块 介 入 其 他 10 个 阶段 的 唯一 方式 ， 是 通过 在 必定 
会 被 调用 的 postconfiguration 方 法 同人 全 局 的 ngx http_core main conf t 结 构 体 的 
phases[INGX_HTTP_ CONTENT_ PHASE] 动态 数组 添加 ngx_http_handler_ pt 处 理 方 法 来 达成 的 ， 
这 个 处 理 方法 将 会 应 用 于 全 部 的 HTTP 请 求 。 





而 第 二 种 方式 是 通过 设置 ngx http core loc_conf t 结 构 体 的 handler 指 针 来 实现 的 ， 在 
10.2.3 节 中 我 们 已 经 知道 ， 每 一 个 location 都 对 应 着 一 个 独立 的 ngx_http_core_ loc_conf t 结 构 
体 。 这 样 ， 我 们 就 不 必 在 必定 会 被 调用 的 postconfiguration 方 法 中 添加 ngx http handler pt 处 理 
方法 了 ， 而 可 以 选择 在 ngx_command t 的 菏 个 配置 项 (如 第 3 章 中 的 mytest 配 置 项 ) 的 回调 方 
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法 中 添加 处 理 方 法 ， 将 当前 location 块 所 属 的 ngx_ http_core loc_conf t 结 构 体 中 的 handler 设 置 
为 ngx_http handler pt 处 理 方法 。 这 样 做 的 好 处 是 ，ngx_http_ handler pt 处 理 方法 不 再 应 用 于 所 
有 的 HTTP 请 求 ， 仪 仪 当 用 户 请 求 的 URIL 配 了 location 时 (也 就 是 mytest 配 置 项 所 在 的 
location) 才 会 被 调用 。 这 也 就 意味 着 它 是 一 种 完全 不 同 于 其 他 阶段 的 使 用 方式 。 








因此 ， 当 HTTP 模 块 实 现 了 某 个 ngx http handler pt 处 理 方法 并 希望 介入 
NGX_HTTP_CONTENT PHASE 阶段 来 处 理 用 户 请 求 时 ， 如 果 和 希望 这 个 ngx_http_handler_pt 方 
法 应 用 于 所 有 的 用 户 请 求 ， 则 应 该 在 ngx http module 人 接口 的 postconfiguration 方 法 中 ， 向 
ngx http core main conf t 结 构 体 的 phases[INGX HTTP CONTENT PHASE] 动 态 数组 中 添加 
ngx_http_handler pt 处 理 方法 ;反之 ， 如 有 果 和 硕 望 这 个 方式 仅 应 用 于 URI 匹 配 了 某 些 location 的 用 
户 请 求 ， 则 应 该 在 一 个 location 下 配置 项 的 回调 方法 中 ， 把 ngx_http handler pt 方法 设置 到 
ngx http_ core loc_conf t 结 构 体 的 handler 中 。 


GG 注意 ”ngx_http_core_loc_conf_t 结 构 体 中 仅 有 一 个 handler 指 针 ， 它 不 是 数组 ， 这 也 就 
意味 着 如 果 采 用 上 述 的 第 二 种 方法 添加 ngx_http_handler_pt 处 理 方 法 ， 那 么 每 个 请 求 在 
NGX_HTIP_CONTENT_PHASE 阶 段 只 能 有 一 个 ngx_http_handler_pt 处 理 方 法 。 而 使 用 第 一 
种 方法 时 是 没有 这 个 限制 的 ，NGX_HTTIP_CONTENT_PHASE 阶 段 可 以 经 由 任意 个 HTTP 模 
块 处 理 。 


当 同 时 使 用 这 两 种 方式 设置 hgx_http_handler_pt 处 理 方法 时 ， 只 有 第 二 种 方式 设置 的 
ngx_http_handler_pt 处 理 方法 才 会 生效 ， 也 就 是 设置 handletr 指 针 的 方式 优先 级 更 高 ， 而 第 一 种 
方式 设置 的 nox_http_handler_ pt 处 理 方 法 将 不 会 生效 。 如 果 一 个 location 配 置 块 内 有 多 个 HTTP 
模块 的 配置 项 在 解析 过 程 都 试图 按照 第 二 种 方式 设置 ngx_http_handler_pt 处 理 方 法 ， 那 么 
面 的 配置 项 将 有 可 能 履 盖 前 面 的 配置 项 解析 时 对 handqdlet 指 针 的 设置 。 


NGX _ HTTP_ CONTENT _ PHASE 阶段 的 checker 方 法 是 ngx http_core_content phase。 
ngx_http _ handler pt 处 理 方法 的 返回 值 在 以 上 两 种 方式 下 具备 了 不 同意 义 。 
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在 第 一 种 方式 下 ，ngx http handler pt 处 理 方 法 无 论 返 回 任何 值 ， 都 会 直接 调用 
ngx_http_finalize_ request 方法 结束 请 求 。 当 然 ，ngx_http_finalize_ request 方法 根据 返回 值 的 不 
同 未 必 会 直接 结束 请 求 ， 这 在 第 11 章 中 会 详细 介绍 。 








在 第 二 种 方式 下 ， 如 果 ngx_http handler pt 处 理 方 法 返回 NGX DECLINED， 将 按 顺序 辐 
后 执行 下 一 个 ngx_http handler pt 处 理 方 法 ， 如 果 返 回 其 他 值 ， 则 调用 ngx_ http_finalize _ request 
方法 结束 请 求 。 


10.6.12 NGX HTTP LOG _ PHASE 阶段 


NGX _ HTTP LOG PHASE 阶 段 是 11 个 HTTP 处 理 阶段 中 的 最 后 一 个 ， 顾 名 思 义 ， 它 是 用 
来 记录 日 志 的 ， 如 ngx_http log module 模 块 就 是 在 这 一 阶段 中 记录 Nginx 访 问 日 记 的 。 如 果 希 
望 在 请 求 的 最 后 阶段 做 一 些 共性 的 收尾 工作 ， 不 妨 将 ngx_http_handler_pt 处 理 方法 添加 到 这 一 
阶段 中 。 


NGX_HTTP_LOG PHASE 阶段 的 checker 方 法 同样 是 ngx_http_core_generic_phase， 因 此 ， 
在 这 一 阶段 中 ，ngx_http handler pt 处 理 方法 的 返回 值 意 义 与 表 10-1 是 完全 相同 的 。 
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10.7 HTTP 框 染 的 初始 化 流程 


本 节 将 综合 10.1 节 ~10.6 节 的 内 容 ， 完 整地 介绍 HTTP 框 架 的 初始 化 过 程 。 实 际 上 ， 这 个 
初始 化 过 程 就 在 ngx_http module 模 块 中 ， 当 配置 文件 中 出 现 了 http 人 配置 块 时 就 回调 
ngx http block 方 法 ， 而 这 个 方法 就 包括 了 HTTP 框 架 的 完整 初始 化 流程 ， 如 图 10-10 所 示 。 





下 面 分 别 介 绍 图 10-10 中 的 15 个 步骤 。 


1) 按照 在 ngx modules 数 组 中 的 顺序 ， 由 0 开始 依次 递增 地 设置 所 有 HTTP 模 块 的 
ctx_index 字 段 。 这 个 字段 的 值 将 决定 HTTP 模 块 应 用 于 请 求 时 的 顺序 。 





2) 第 2 步 ~ 第 7 步 实 际 上 就 是 10.2.1 节 中 描述 的 内 容 。 解 析 到 htp 他 块 时 产生 1 个 
ngx_http_conf ctx t 结 构 体 ， 同 时 初始 化 它 的 main conf、srv_conf、loc_conf3 个 指针 数组 ， 数 
组 的 容量 就 是 第 1 步 中 获取 到 的 所 有 HTTP 模 块 的 数量 。 





3) 依次 调用 所 有 HTTP 模 块 的 create main conf 方 法 ， 产 生 的 配置 结构 体 指 针 将 按照 各 模 
块 ctx index 字 段 指定 的 顺序 放 入 ngx http_conf ctx t 结 构 体 的 main conf 数 组 中 。 


4) 依次 调用 所 有 HTTP 模 块 的 create_srv_conf 方 法 ， 产 生 的 配置 结构 体 指 针 将 按照 各 模 
块 ctx index 字 段 指定 的 顺序 放 入 ngx http_conf ctx tt 结构 体 的 srv_con 伏 组 中 。 


5) 依次 调用 所 有 HTTP 模 块 的 create loc conf 方 法 ， 产 生 的 配置 结构 体 指 针 将 按照 各 模 
块 ctx index 字 段 指定 的 顺序 放 入 ngx http_conf ctx t 结 构 体 的 loc con 仙 b 组 中 。 


6) 依次 调用 所 有 HTTP 模 块 的 preconfiguration 方 法 。 
7) 解析 http 个 块 下 的 main 级 别 配 置 项 。 


8) 依次 调用 所 有 HTTP 模 块 的 init main_conf 方 法 。 
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门 初 娩 化 所 有 HTTP 
模块 的 ctx_index 序号 


2 ) 分配 解析 main 级 别 配 置 项 时 存放 
HTTP 模 块 结构 体 指针 的 3 个 数组 


3 ) 调 用 所 有 HTTP 
模块 的 create_main_conf 方法 


4) 调用 所 有 HTTP 
模块 的 create_srv_conf 方法 


5) 调用 所 有 HTTP 
模块 的 create loc_conf 方法 


6 ) 调 用 所 有 HTTP 
模块 的 preconfiguration 方 法 


7) 解析 http{} 


{ 
块 下 的 所 有 main 级 别 配置 项 


8 ) 调用 所 有 HTTP 
模块 的 init_main_ conf 方 法 


9 ) 合并 main 、svr 、loc 级 别 下 
server 、location 相 关 的 配置 项 


10) 构造 location 


组 成 的 静态 二 又 平衡 查找 树 


11) 初始 化 可 添加 处 理 方 法 的 
7 个 HTTP 阶 段 的 动态 数组 


12) 调用 所 有 HTTP 模 块 的 
postconfiguration 方 法 使 之 可 以 介入 HTTP 阶 段 





13) 根据 各 HTTP 模 块 介入 的 处 理 方法 构造 出 
phase_engine handlers 数组 .| 






14) 构造 server 
虚拟 主机 构成 的 支持 通配符 的 散 列 表 








15 ) 构造 监听 端口 与 server 
间 的 关联 关系 , 设置 新 连接 事件 的 回调 方法 
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图 10-10 ” HTTP 框架 的 初始 化 流程 


@@ 注音。 在 解析 main 级 别 配置 项 时 ， 如 果 允 到 server{} 配置 据 ， 将 会 甬 改 
nex_http_core_server 方 法 ， 并 开始 解析 server 级 别 下 的 配置 项 ， 这 一 过 程 可 参见 10.2.2 节 。 在 解 
析 strv 级 别 配 置 项 时 ， 如 果 允 到 location{} 配 置 块 ， 将 会 触发 ngx_http_core_location 方 法 ， 并 开 


始 解析 location 级 别 下 的 配置 项 ， 这 一 过 程 可 参见 10.2.3 节 。 


9) 调用 ngx_http _ merge_servers 方 法 合并 配置 项 ， 这 一 步骤 的 内 容 与 10.2.4 节 介绍 的 多 级 
别 配 置 项 合并 是 一 致 的 。 





10) 按照 10.5$ 节 介绍 的 方式 ， 创 建 由 location 块 构造 的 静态 二 又 平衡 查找 树 。 


11) 在 10.6 节 中 我 们 介绍 过 ， 有 7 个 HTTP 阶 段 (NGX _HTTP POST READ PHASE、 
NGX HTTP SERVER REWRITE PHASE、 NGX HTTP REWRITE PHASE、 
NGX HTTP PREACCESS PHASE、NGX HTTP ACCESS PHASE. 
NGX HTTP CONTENT PHASE、NGX HTTP LOG PHASE) 是 允许 任何 一 个 HTTP 模 块 实 
现 目 己 的 ngx_ http handler pt 处 理 方 法 ， 并 将 其 加 入 到 这 7 个 阶段 中 去 的 。 在 调用 HTTP 模 块 的 
postconfiguration 方 法 疝 这 7 个 阶段 中 添加 处 理 方法 前 ， 需 要 先 将 phases 数 组 中 这 7 个 阶段 里 的 
handlers 动 态 数 组 初始 化 (ngx_array t 类 型 需要 执行 ngx array_init 方 法 初始 化 )， 在 这 一 步 又 
中 ， 通 过 调用 ngx_http_init phases 方 法 来 初始 化 这 7 个 动态 数组 。 


12) 依次 调用 所 有 HTTP 模 块 的 postconfiguration 方 法 。HTTP 模 块 可 以 在 这 一 步 又 中 将 自 
己 的 ngx_http handler pt 处 理 方法 添加 到 以 上 7 个 HTTP 阶段 中 。 


13) 在 上 一 步 中 ， 各 HTTP 模 块 会 向 全 局 的 ngx_http_core main _ conf 结构 体 中 的 phases 数 
组 添加 处 理 方 法 ， 该 数组 中 存在 11 个 成 员 ， 每 个 成 员 都 是 动态 数组 ， 可 能 包含 任何 数量 的 处 
理 方法 。 这 一 步 又 将 遍历 以 上 所 有 处 理 方 法 ， 构 造 由 所 有 处 理 方 法 构成 的 有 序 的 
phase_engine.handlers 数 组 。 关 于 HTTP 阶 段 的 用 法 可 参见 10.6 节 。 
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14) 这 一 步骤 构造 server 虚 拟 主机 构成 的 文 持 通配符 的 散 列 表 ， 可 参见 10.4 节 的 内 容 。 


15) 这 一 步骤 构造 监听 端口 与 server 间 的 关联 关系 ， 设 置 新 连接 事件 的 回调 方法 为 


ngx http init connection， 可 参见 10.3 节 。 


以 上 15 个 步 又 就 是 HTTP 框 染 在 Nginx 的 局 动 过 程 中 所 做 的 主要 工作 。 
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10.8 小结 


本 章 介 绍 了 静态 的 HTTP 框 架 ， 主 要 讨论 了 http 配 置 项 的 管理 与 合并 操作 ， 以 及 HTTP 框 
染 怎 样 设计 server 和 1location 的 数据 结构 以 期 快速 选择 server 和 location 处 理 用 户 请 求 ， 监 听 地 
址 是 如 何 与 server 关 联 起 来 的 ， 同 时 介绍 了 HTTP 的 11 个 处 理 阶 段 及 其 设计 原理 和 使 用 方法 。 
通过 了 解 这 些 内 容 ， 读 者 可 以 从 HTTP 框 架 的 角度 了 解 HTTP 模 块 的 运行 机 制 。 男 外 ， 本 章 扩 
展 了 第 3 章 中 介绍 的 单一 的 HTTP 模 块 设计 方法 ， 特 别 是 根据 10.6 市 介绍 的 内 容 ， 可 以 设计 出 
更 加 强大 的 HTTP 模 块 ， 深 入 地 介入 到 任何 一 个 HTTP 处 理 阶 段 中 。 





本 章 并 没有 涉及 HTTP 框 架 是 如 何 处 理 用 户 请 求 的 ，HTTP 框 架 的 动态 处 理 流程 将 在 第 11 


章 中 介绍 。 
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第 11 章 HTTP 框架 的 执行 流程 





本 章 将 介绍 动态 的 HTTP 框 架 ， 主 要 探讨 在 请 求 的 生命 周期 中 ， 基 于 事件 驱动 的 HTTP 框 
架 是 怎样 处 理 网 络 事件 以 及 怎样 集成 各 个 HTTP 模 块 来 共同 处 理 HTTP 请 求 的 ， 同 时 ， 还 会 介 
绍 为 了 简化 HTTP 模块 的 开发 难度 而 提供 的 多 个 非 阻塞 的 异步 方法 。 本 章 内 容 与 第 9 章 介 绍 的 
事件 模块 密切 相关 ， 同 时 还 会 使 用 到 第 10 章 介绍 过 的 http 配 置 项 和 11 个 阶段 。 另 外 ， 本 书 第 
二 部 分 讲述 了 怎样 开发 HTTP 模 块 ， 本 章 将 会 回答 为 什么 可 以 这 样 开 发 HTTP 模 块 。 


HTTP 框 架 存在 的 主要 目的 有 两 个 : 


* Nginx 事 件 框 架 主要 是 针对 传输 层 的 TCP 的 ， 作 为 Web 服 务 器 HTTP 模 块 需要 处 理 的 则 
是 HTTP，HTTP 框 架 必须 要 针对 基于 TCP 的 事件 框架 解决 好 HTIP 的 网 络 传输 、 解 析 、 组 装 


等 问题 。 


` 虽然 事件 驱动 架构 在 性 能 上 是 不 错 的 ， 但 它 的 开发 效率 并 不 高 ， 而 HTTP 模 块 的 业务 
通常 较 复 杂 ， 我 们 希望 HTTP 模 块 在 拥有 事件 框架 的 高 性 能 优势 的 同时 ， 尽 量 只 关注 业务 。 
这 样 ，HITP 框 架 就 需要 为 HTTP 模 块 屏蔽 事件 驱动 架构 ， 使 得 HTTP 模 块 不 需要 关心 网 络 事 
件 的 处 理 ， 同 时 又 能 灵活 地 介入 那 11 个 阶段 中 以 处 理 请 求 。 


根据 以 上 HTTP 框 架 的 设计 目的 ， 我 们 再 来 看 HTTP 框 架 在 动态 执行 中 的 大 概 流程 : 先 与 
客户 端 建 立 TCP 连 接 ， 接 收 HTTP 请 求 行 、 头 部 并 解析 出 它们 的 意义 ， 再 根据 nginx.conf 配 置 
文件 找到 一 些 HTTP 模 块 ， 使 其 依次 合作 着 处 理 这 个 请 求 。 同 时 为 了 简化 HTTP 模 块 的 开发 ， 
HTTP 框 架 还 提供 了 接收 HTTP 包 体 、 发 送 HTTP 响 应 、 派 生子 请 求 等 工具 和 方法 。 

















对 于 TCP 网 络 事 件 ， 可 粗略 地 分 为 可 读 事 件 和 可 写 事 件 ， 然 而 可 读 事件 中 又 可 细 分 为 收 
到 SYN 包 带 来 的 新 连接 事件 、 收 到 FIN 包 带 来 的 连接 关闭 事件 ， 以 及 套 接 字 绥 冲 区 上 真正 收 
到 TCP 流 。 可 写 事件 虽然 相对 简单 点 ， 但 Nginx 提 供 限 制 速度 功能 ， 有 时 可 写 事 件 触发 时 未 必 


可 以 去 个 岗 证 一 同时 玲子 情 只 二 耻 运 名 洛 于 供 才 巡 和 ES 这 





事件 的 管理 都 需要 依靠 HTTP 框 架 ， 这 给 HTTP 框 架 带 来 了 复杂 性 。 在 清楚 了 解 这 些 设计 后 ， 
我 们 将 对 HTTP 模 块 的 开发 有 一 个 非常 透彻 的 认识 ， 因 为 HTTP 模 块 完 全 是 由 HTTP 框 架设 
计 、 定 义 的 ， 它 就 像 Android 应 用 程序 与 Android 操 作 系 统 间 的 关系 。 同 时 ， 深 入 了 解 HTTP 框 
架 后 ， 读 者 会 明白 如 何 把 复杂 的 事件 驱动 机 制 从 关注 于 业务 的 模块 中 分 离 ， 这 些 设计 方法 都 
是 值得 读者 学 习 的 。 
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11.1 HITP 框 架 执 行 流 程 概述 





本 章 在 介绍 HITP 框 以 的 同时 会 说 明 它 怎样 使 用 事件 模块 提供 的 操作 方法 ， 在 这 之 前 ， 
先 来 回顾 一 下 第 9 章 中 关于 事件 驱动 模式 的 内 容 。 





个 事件 都 是 由 ngx_event t 结 构 体 表示 的 ， 而 TCP 连 接 则 由 ngx_connection t 结 构 体 表 
示 ，HTTP 请 求 晤 无 疑问 是 基于 一 个 TCP 连 接 实现 的 。 每 个 TCP 连 接 包 括 一 个 读 事 件 和 一 个 写 
事件 ， 它 们 放 在 ngx_connection t 中 的 read 成 员 和 write 成 员 中 。 通 过 事件 模块 提供 的 
ngx handle read event 方 法 和 ngx handle write event 方 法 ， 可 以 把 相应 的 事件 添加 到 epoll 中 ， 
我 们 可 以 期 待 在 满足 事件 触发 条 件 时 ，Nginx 进 程 会 调用 ngx_event 事件 的 handler 回 调 方 法 执 
行业 务 。 而 通过 事件 模块 提供 的 ngx_add_timer 方 法 可 以 将 上 面 的 读 事 件 或 者 写 事件 添加 到 定 
时 器 中 ， 在 满足 超时 条 件 后 ，Nginx 进 程 同样 会 调用 ngx_event t 事 件 的 handler 回 调 方法 执行 业 
务 。 








在 第 3 半 开 及 HTTP 模 块 时 ， 并 没有 看 到 事件 模块 的 有 影子， 但 HTTP 框 架 确 实 是 依 徘 事件 
驱动 机 制 实现 的 。 基 于 这 一 点 ， 先 来 总 结 一 下 HTTP 框 架 需 要 完成 的 最 主要 的 4 项 工作 。 








HTTP 框 架 需 要 完成 的 第 一 项 工作 是 集成 事件 驱动 机 制 ， 管 理 用 户 发 起 的 TCP 连 接 ， 处 
理 网 络 读 / 写 事件 ， 并 在 定时 器 中 处 理 请 求 超时 的 事件 。 这 些 内 容 将 在 11.2 节 ~11.5 节 介绍 ， 
其 中 11.2 节 会 讨论 新 连接 建立 成 功 后 HTTP 框架 的 行为 ，11.3 节 介绍 第 一 个 网 络 可 读 事件 到 达 
后 HITP 框 架 的 行为 ，11.4 节 介绍 在 没有 接收 到 完整 的 HTTP 请 求 行 之 前 HTTP 框 架 押 要 完成 的 
工作 ，11.5 节 介绍 在 没有 接收 到 完整 的 HTTP 请 求 头 部 之 前 HTTP 框 架 所 要 完成 的 工作 。 





HTTP 框 架 需 要 完成 的 第 二 项 工作 是 与 各 个 HTTP 模块 共同 处 理 请 求 。 实 际 上 ， 通 过 第 3 
章 的 例子 我 们 已 经 知道 ， 只 有 请 求 的 URI 与 1ocation 配 置 匹配 后 HTTP 框 架 才 会 调度 HTTP 模 块 
处 理 请 求 。 而 在 第 10 章 中 也 已 看 到 ，HTTP 框 架 定 义 了 11 个 阶段 ， 其 中 4 个 基本 的 阶段 只 能 


HTTP 框 架 处 理 ， 其 余 的 7 个 阶段 可 以 让 各 HTTP 模 块 介 入 来 共同 处 理 请 求 。 因 此 ，HTTP 框 架 
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需要 在 这 7 个 阶段 中 调度 合适 的 HTTP 模 块 处 理 请 求 。 第 11.6 节 中 将 介绍 HTTP 框 架 如 何 调度 
HTTP 模 块 参与 到 请 求 的 处 理 中 。 


第 三 项 工作 与 第 5 章 介 绍 过 的 subrequest 功 能 有 关 。 为 了 实现 复杂 的 业务 ，HTTP 框 架 允 许 
将 一 个 请 求 分 解 为 多 个 子 请 求 ， 当 然 ， 子 请 求 还 可 以 继续 向 下 派生 “孙子 请求， 这样 就 可 以 
把 复杂 的 功能 分 散 到 多 个 子 请 求 中 ， 每 个 子 请 求 仅 专 注 于 一 个 功能 。 这 种 设计 也 是 一 种 平 
衡 ， 使 用 事件 驱动 机 制 在 提高 性 能 的 同时 其 实 大 大 增加 了 程序 的 复杂 度 ， 特 别 是 开发 复杂 功 
能 时 太 多 事件 的 处 理会 让 代码 混乱 不 堪 ， 而 子 请 求 的 派生 则 可 以 降低 复杂 度 ， 使 得 Nginx 可 
以 提供 多 样 化 的 功能 。 在 第 11.7 节 中 ， 将 讨论 HTTP 框架 是 如 何 设计 、 实 现 subrequest 功 能 
的 。 











HTTP 框 架 的 第 四 项 工作 则 是 提供 基本 的 工具 接口 ， 供 各 HTTP 模 块 使 用 ， 诸 如 接收 
HTTP 包 体 ， 以 及 发 送 HITP 啊 应 头 部 、 响 应 包 体 等 。 在 11.8 节 中 将 说 明 HITP 框 架 提 供 的 接收 
HTTP 包 体 功 能 ，11.9 节 将 说 明 发 送 HTTP 响 应 是 怎样 实现 的 ， 在 11.10 节 中 将 讨论 如 何 结束 
HTTP 请 求 。 为 什么 要 专门 讨论 请 求 的 结束 呢 ? 因为 在 基于 事件 驱动 的 HTTP 框 架 中 ， 由 于 每 
个 HTTP 模块 仅 能 在 某 一 时 刻 介 入 到 请 求 中 ， 所 以 有 时 候 它 需要 表达 一 种 希望 “ 延 后 ”结束 请 
求 的 意思 ， 这 一 特性 造成 了 结束 请 求 的 动作 十 分 复杂 ， 因 而 使 用 独立 的 一 节 来 专门 说 明 。 














本 章 的 全 部 内 容 就 是 在 探讨 如 何 完成 以 上 四 项 工作 。 
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11.2 ”新 连接 建立 时 的 行为 





当 Nginx 接 收 到 用 户 及 起 TCP 连 接 的 请 求 时 ， 事 件 框架 将 会 负 贡 把 TCP 连 接 建 立 起 来 ， 如 
果 TCP 连 接 成 功 建立 ，HTTP 框 架 就 会 介入 请 求 的 处 理 了 ， 如 图 9-5 所 示 ， 在 ngx_event accept 
方法 建立 新 连接 的 最 后 1 步 ， 将 会 调用 ngx listening t 监 听 结 构 体 的 handler 方 法 。 在 10.3 节 中 讲 
过 ，HTTP 框 架 在 初始 化 时 就 会 将 每 个 监听 ngx_listening t 结 构 体 的 handler 方 法 设 为 





ngx http init connection 方 法 ， 如 下 所 示 。 





void ngx http init connection(ngx connection t *c) 





即 HITP 框 架 处 理 请 求 的 第 一 步 就 在 ngx http init connection 方 法 中 ， 这 里 传 入 的 参数 c 就 
是 新 建立 的 连接 。 图 11-1 列 举 了 ngx http_init connection 方 法 所 做 的 主要 工作 。 
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1) 设置 可 该 事件 
的 回调 方法 
[检查 是 否 有 可 读 的 TCP 流 ] 


[未 接收 到 TCP 流 ] 





[接收 到 TCP 流 | 


2 ) 执行 ngx_http_init_request 
初始 化 请 求 并 处 理 TCP 流 


3) 将 可 读 事件 加 入 到 定时 需 中 以 
监控 接收 请 求 是 个 超时 





4) 将 可 读 事 件 加 入 到 


epoll 中 






二 


图 11-1 建立 连接 成 功 后 HTTP 框 架 的 行为 


下 面 简单 解释 一 下 图 11-1 中 的 4 个 步骤 : 





1) 将 新 建立 的 连接 c 的 可 读 事 件 处 理 方 法 设置 为 ngx_http_init request。 在 9.3 节 我 们 介绍 


过 ngx_ connection t 结 构 体 中 会 用 read 成 员 表 示 


读 / 写 事件 均 使 用 ee 构 体 表示 。 在 9.2 节 中 又 介 
又 实际 上 就 是 把 连接 c 的 read 读 事件 的 handler 方 法 设 为 


调用 其 中 的 handler 方 法 。 这 一 











连接 上 的 可 读 事 件 ，write 成 员 表 示 可 写 事件 。 
过 每 个 事件 发 生 时 事件 框架 都 会 





ngx_http_init request， 它 意味 着 当 用 户 | 数据 到 达 服 务 器 后 ， 


中 HH DT DD 
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ngx_http_init_ request 方法 将 会 被 调用 《参见 11.3 节 ) 。 


事实 上 ， 对 于 可 写 事 件 ， 也 会 设置 它 的 handler 回 调 方法 为 ngx http empty handler， 这 个 
方法 不 会 做 任何 工作 ， 如 下 所 示 。 





void ngx http empty handler (ngx event 七 *wev) 

{ 
ngx log debug0 (NGX LOG DEBUG HTTP, wev->log, 0, "http empty handler"); 
returns 





} 





这 个 方法 仅 有 一 个 用 途 : 当 业 务 上 不 需要 处 理 可 写 事 件 时 ， 就 把 ngx_http_ empty handler 
方法 设置 到 连接 的 可 写 事件 的 handler 中 ， 这 样 可 写 事件 被 定时 器 或 者 epoll 触 发 后 是 不 做 任何 
.EH 


@ 注意 ”下 面 会 多 次 使 用 nex_http_empty_handler 方 法 。 


2) 如 果 新 连接 的 读 事 件 ngx_event t 结 构 体 中 的 标志 位 ready 为 1， 实 际 上 表示 这 个 连接 对 
应 的 套 接 字 绥 存 上 已 经 有 用 户 发 来 的 数据 ， 这 时 就 可 调用 上 面 说 过 的 ngx http_init request 方 
法 处 理 请 求 ， 参 见 11.3 节 。 





3) 在 9.7.3 节 的 表 9-$ 中 我 们 介绍 过 定时 器 的 用 法 ， 在 这 一 步骤 中 将 调用 ngx add_timer 方 
法 把 读 事件 添加 到 定时 器 中 ， 设 置 的 超时 时 间 则 是 nginx.conf 中 client header timeout 配 置 项 指 
定 的 参数 。 也 就 是 说 ， 如 果 经 过 client header timeout 时 间 后 这 个 连接 上 还 没有 用 户 数据 到 
达 ， 则 会 由 定时 器 触发 调用 读 事件 的 ngx_http_init request 处 理 方 法 。 








4) 我 们 在 9.2.1 节 中 介绍 过 ngx handle read event 方 法 ， 它 可 以 将 一 个 事件 添加 到 epoll 
中 。 在 这 一 步骤 中 ， 将 调用 ngx_handle_ read_event 方 法 把 连接 c 的 可 读 事 件 添 加 到 epoll 中 。 注 
意 ， 这 里 并 没有 把 可 写 事 件 添加 到 epoll 中 ， 因 为 现在 不 需要 回 客 户 端 发 送 任何 数据 。 














以 上 4 个 步骤 就 是 ngx http_init connection 方 法 的 主要 工作 ， 也 就 是 新 连接 建立 成 功 时 
HTTP 框 架 对 请 求 的 处 理 。 
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11.3 ”第 一 次 可 读 事件 的 处 理 


当 TCP 连 接 上 第 一 次 出 现 可 读 事件 时 ， 将 会 调用 ngx http_init request 方 法 初始 化 这 个 
HTTP 请 求 ， 如 下 所 示 。 


static void ngx http init request (ngx event 七 *rev) 





实际 上 ，HTTP 框 架 并 不 会 在 连接 建 并 成 功 后 就 开始 初始 化 请 求人 参见 11.2 市 ) ， 而 是 在 
个 连接 对 应 的 套 接 字 缓冲 区 上 确实 接收 到 了 用 户 发 来 的 请 求 内 容 时 才 进 行 ， 这 种 设计 体现 
了 Nginx 出 于 高 性 能 的 考虑 ， 这 样 减少 了 无 请 的 内 存 消 耗 ， 降 低 了 一 个 请 求 占用 内 存 资源 的 
时 间 。 因 此 ， 当 有 些 客户 端 建立 起 TCP 连 接 后 一 直 没 有 发 送 内 容 时 ，Nginx 是 不 会 为 它 分 配 和 内 
存 的 。 








从 11.2 节 中 可 以 看 出 ， 在 有 些 情 况 下 ， 当 TCP 连 接 建 立成 功 时 同时 也 出 现 了 可 读 事 件 
〈 例 如， 在 套 接 字 设置 了 deferred 选 项 时 ， 内 核 仅 在 套 接 字 上 确实 收 到 请 求 时 才 会 通知 epoll 
调度 事件 的 回调 方法 ) ， 这 时 ngx_http_init_request 方 法 是 在 图 11-1 的 第 2 步 中 执行 的 。 当 然 ， 
在 大 部 分 情况 下 ，ngx http init request 方 法 和 ngx http init connection 方 法 都 是 由 两 个 事件 
CTCP 连 接 建 立成 功 事件 和 连接 上 的 可 读 事件 ) 触发 调用 的 。 图 11-2 中 展示 了 在 
ngx_http_init_ request 方法 中 究竟 做 了 哪些 工作 。 
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ek 





[已 经 超时 ] 
2 构造 ngx_ http_request_1 
结构 体 并 设置 到 连接 的 data 成 员 





3 ) 找 到 监听 地 址 对 应 
的 默认 server 


4) 设 置 这 个 请 求 对 应 的 
http 配 置 项 


5) 重 新 设置 连接 读 事件 的 回调 方法 为 


ngx_http_process_request_line 









6) 创建 接收 
缓冲 区 


1 ) 调 用 ngx_http_close_ connection 


方法 关闭 连接 





7) 创 建 ngx_http_request_t 
结构 体 的 内 存 池 










8) 初始 化 ngx_http_request_t 
结构 体 中 的 容器 






9) 创 建 指针 数组 以 存放 所 有 HTTP 
模块 对 该 请 求 可 能 创建 的 上 下 文 结构 体 


10) 更 新 ngx_http_ request_1 
结构 体 的 请 求 开 始 时 间 


11) 调 用 ngx_http_process_request_line 


接收 HTTP 请 求 行 
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图 11-2 第 一 次 接收 到 可 读 事件 后 的 行为 


从 图 11-2 中 可 以 看 出 ， 第 一 次 读 事 件 的 回调 方法 ngx_http_init_request 主 要 做 了 3 件 事 : 对 
请 求 构造 ngx_http_request t 结 构 体 并 初始 化 部 分 参数 、 修 改 读 事 件 的 回调 方法 为 
ngx_http_process_request_line 并 调用 该 方法 开始 接收 并 解析 HTTP 请 求 行 。 下 面 详细 分 析 图 11- 


2 中 的 11 个 步骤 : 


1) 首先 回顾 一 下 图 11-1 的 第 3 步 ， 那 里 曾经 将 恋 事 件 也 添加 到 了 定时 器 中 ， 超 时 时 间 就 
是 配置 文件 中 的 client header _ timeout， 因 此 ， 首 先 要 检查 读 事 件 是 人 否 已 经 超时 ， 也 残 是 检 碍 
ngx event t 事 件 的 timeout 成 员 是 否 为 1。 如 果 timeout 为 1， 则 表示 接收 请 求 已 经 超时 ， 则 不 应 
该 继续 处 理 该 请 求 ， 于 是 调用 ngx http_close request 方 法 关闭 请 求 ， 同 时 由 
ngx http init request 方 法 中 返回 。ngx http_close request 方 法 的 详细 介绍 可 参见 11.10.3 节 。 














2) 在 第 3 章 介 绍 HITP 模 块 的 开发 时 曾 提 到 ， 每 个 请 求 都 会 有 一 个 ngx_http_request t 结 构 
体 ， 所 有 的 HITP 模 块 都 以 此 作为 核心 结构 体 来 处 理 请 求 。 这 个 ngx_http_request t 结 构 体 就 是 
在 此 步骤 中 创建 的 ， 同 时 还 将 这 个 关键 结构 体 的 地 址 存放 到 表示 TCP 连 接 的 ngx_connection f 
结构 体 中 的 data 成 员 上 。 这 一 步 中 还 会 把 表示 这 个 ngx_connection t 结 构 体 被 使 用 次 数 的 


requests 成 员 加 1。11.3.1 节 将 会 详细 介绍 ngx_http_request t 结 构 体 。 


3) 从 10.3 贡 可 以 看 出 ， 配 置 文件 的 每 个 server{} 块 中 都 可 以 针对 不 同 的 本 机 下 地 址 监听 
同一 个 端口 ， 事 实 上 每 一 个 监听 对 象 ngx_listening t 都 会 对 应 着 监听 这 个 端口 的 所 有 监听 地 
址 。 回 顾 一 下 8.3.1 节 ，ngx_listening ft 结构 体 中 有 一 个 servers 指 针 ， 在 HTTP 框 染 中 ， 它 指 问 
监听 这 一 端口 的 所 有 监听 地 址 ， 而 每 个 监听 地 址 也 包含 了 其 所 属 server 块 的 配置 项 ， 如 下 所 


小 。 





typedef struct { 


ngx http core srv conf t *default server; ngx http virtual names t *virtual names; } ngx http addr conf t 














default_ server 也 就 是 这 个 监听 地 址 对 应 的 server 块 配置 信息 ， 在 第 10 章 中 我 们 曾经 介绍 
过 ngx_http_core_srv_conf {结构 体 是 如 何 管理 配置 信息 的 。 这 一 步 中 将 会 遍历 ngx_listening t 
结构 体 的 servers 指 向 的 数组 ， 找 到 合适 的 监听 地 址 ， 然 后 找到 默认 的 server 虚 拟 主 机 对 应 的 
ee ii 生 站 移居 : 


4) 在 第 2 步 建立 好 的 ngx_http_request t 结 构 体 中 ，main conf、srv_conf、loc_conf 这 3 个 成 
员 表 示 这 个 请 求 对 应 的 main、srv、loc 级 别 的 配置 项 ， 这 时 会 通过 刚刚 获取 到 的 默认 的 
ngx_http_core_srv_conf t 结 构 体 设置 (10.2 节 中 介绍 过 ，ngx_http_core_srv_conf t 结 构 体 具有 
一 个 ngx_http_conf ctx {类 型 的 成 员 ctx， 从 这 里 可 以 获取 到 3 个 级 别 的 配置 项 指针 数组 〉。 


5) 第 一 次 读 事 件 的 回调 方法 是 ngx http init request， 它 仅 用 于 初始 化 请 求 ， 之 后 的 读 事 
件 意味 着 接收 到 请 求 内 容 ， 显 而 易 见 ， 它 的 回调 方法 是 需要 改变 一 下 的 ， 即 在 这 一 步 中 将 把 
这 个 读 事件 的 回调 方法 设 为 ngx_http process_request line， 这 个 方法 将 会 负责 接收 并 解析 出 
完整 的 HTTP 请 求 行 。 








6) 读 事 件 被 触发 ， 其 实 就 意味 着 对 应 的 套 接 字 缓冲 区 上 已 经 接收 到 用 户 的 请 求 了 ， 这 
时 需要 在 用 户 态 的 进程 空间 分 配 内 存 ， 用 来 把 内 核 缓冲 区 上 的 TCP 流 复制 到 用 户 态 的 内 存 
中 ， 并 使 用 状态 机 来 解析 它 是 否 是 合法 的 、 完 整 的 HTTP 请 求 。 这 一 步 将 在 ngx_connection + 
的 内 存 池 中 分 配 一 块 内 存 ( 读 者 可 以 思考 为 何 没有 在 ngx_http_request t 结 构 体 的 内 存 池 中 分 
配 接收 请 求 的 缓存 ) ， 内 存 块 的 大 小 与 nginx.conf 文 件 中 的 client_ header_ buffer_ size 配置 项 参 
数 一 致 ，ngx_connection t 绪 构 体 的 buffer 指 针 以 及 ngx_http_request t 结 构 体 的 header_in 指 针 共 
同 指向 这 块 内 存 缓冲 区 。 这 个 header_in 绥 冲 区 (除了 在 11.8.1 节 外 )〉 将 负责 接收 用 户 发 送 来 
的 请 求 内 容 。 当 这 个 TCP 连 接 复 用 于 其 他 HTTP 请 求 时 ， 这 个 buffer 指 针 指 向 的 内 存 仍然 是 可 
用 的 ， 新 的 HITP 请 求 初始 化 执行 到 这 一 步 时 ， 就 不 用 再 次 由 ngx_connection t 的 内 存 池 分 配 
内 存 了 。 








7) ngx_http request t 结 构 体 同 样 有 一 个 内 存 池 ，HTTP 模 块 更 应 该 在 ngx_http_request tt 结 


NS 





的 内 存 都 会 及 时 回收 。 这 一 步 中 将 会 创建 这 个 内 存 池 ， 内 存 池 的 初始 大 小 由 nginx.conf 文 件 中 
的 request pool size 配 置 项 参数 决定 。 这 个 内 存 池 只 会 在 11.10.2 节 中 介绍 的 


ngx http free _ request 方法 中 销毁 。 


8) 初始 化 ngx http_ request t 结 构 体 中 的 部 分 容器 ， 如 headers_out 结 构 体 中 的 ngx_list t 类 
型 的 headers 链 表 、variables 数 组 等 。 


9) 在 4.5 节 曾经 讲 过 ， 每 个 HTTP 模 块 都 可 以 针对 一 个 请 求 设置 上 下 文 结构 体 ， 并 通过 
ngx_http_set_ctx 和 ngx_http_get_module_ctx 宏 来 设置 和 获取 上 上 下文。 那么 ， 这 些 HTTP 模 块 针 对 
请 求 设置 的 上 下 文 结构 体 指针 ， 实 际 上 是 保存 到 ngx_http request t 结 构 体 的 ctx 指 针 数 组 中 
的 。 在 这 一 步骤 中 ， 会 分 配 一 个 具有 nsx http max module (HTTP 模 块 的 总 数 ) 个 成 员 的 指 
针 数 组 ， 也 就 是 说 ， 为 每 个 HTTP 模 块 都 提供 一 个 位 置 存放 上 下 文 结构 体 的 指针 。 


10) ngx_http_request t 结 构 体 中 有 两 个 成 员 表示 这 个 请 求 的 开始 处 理 时 间 : start sec 成 员 
和 start_ msec 成 员 。 这 一 步 中 将 会 初始 化 这 两 个 成 员 。 在 11.9.2 节 中 将 会 看 到 这 两 个 成 员 的 用 
法 ， 它 们 会 为 限 速 功能 服务 。 


11) 调用 ngx http process_request line 方 法 开始 接收 、 解 析 HTTP 请 求 行 。 


以 上 步骤 构成 了 ngx _http init request 方 法 的 主要 内 容 ， 其 中 构造 的 ngx_http_request t 结 构 
体 在 接 下 来 的 小 节 中 会 详细 介绍 。 








从 第 3 章 开 始 ， 我 们 已 经 多 次 见 过 ngx_http_request t 结 构 体 了 ， 但 大 多 是 站 在 HTTP 模 块 
的 角度 来 思考 如 何 使 用 Nginx 已 经 为 我 们 构造 好 的 ngx_http_request t 结 构 体 。 本 节 再 次 介绍 
ngx_http_request t 结 构 体 ， 则 是 站 在 HTTP 框 架 的 角度 来 思考 如 何 完 成 HTTP 框 架 的 基本 功 
能 。 下 面 首 先 说 明 它 与 HTTP 框 架 密切 相关 的 成 员 。 





typedef struct ngx http request s ngx http redquest 七 struct ngx http request s { 


// 这 个 请 求 对 应 的 客户 端 连接 
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ngx connection 七 *connection; 
// 指向 存放 所 有 


HTTP 模 块 的 上 下 文 结 构 体 的 指针 数组 


void **ctx; 
// 指向 请 求 对 应 的 存放 


main 级 别 配 置 结 构 体 的 指针 数组 


void **main conf; 
// 指向 请 求 对 应 的 存放 


srv 级 别 配 置 结构 体 的 指针 数组 


void **srv conf; 
// 指向 请 求 对 应 的 存放 


loc 级 别 配置 结构 体 的 指针 数组 


VOLd. **Loc :Gonfs 
/* 在 接收 完 


HTTP 头 部 ， 第 一 次 在 业务 上 处 理 
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HTTP 请 求 时 ， 


HTTP 框 架 提供 的 处 理 方法 是 


ngx_http process request。 但 如 果 该 方法 无 法 一 次 处 理 完 该 请 求 的 全 部 业务 ， 在 归还 控制 权 到 


epoll 事 件 模块 后 ， 该 请 求 再 次 被 回调 时 ， 将 通过 


ngx_http request handler 方 法 来 处 理 ， 而 这 个 方法 中 对 于 可 读 事件 的 处 理 就 是 调用 


read event handler 处 理 请 求 。 也 就 是 说 ， 


HTTP 模 块 希望 在 底层 处 理 请 求 的 读 事 件 时 ， 重 新 实现 





read event handler 方 法 


Wa 


ngx http event handler pt read event handler; /* 与 





read event handler 回 调 方 法 类 似 ， 如 果 
ngx_http request handler 方 法 判断 当前 事件 是 可 写 事 件 ， 则 调用 
write event handler 处 理 请 求 。 
ngx_http request handler 的 流程 可 参见 图 
11-7*/ 
ngx http event handler pt write event handler; // upstream 机 制 用 到 的 结构 体 ， 在 第 


12 章 中 会 详细 说 明 


ngx http upstream t *upstream; 


/* 表 示 这 个 请 求 的 内 存 池 ， 在 
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ngx http free _ request 方法 中 销毁 。 它 与 


ngx_connection 七 中 的 内 存 池 意 义 不 同 ， 当 请 求 释放 时 ， 


TCP 连 接 可 能 并 没有 关闭 ， 这 时 请 求 的 内 存 池 会 销毁 ， 但 


ngx_connection 七 的 内 存 池 并 不 会 销毁 


*/ 


ngx Pool t *pool; 


// 用 于 接收 


HTTP 请 求 内 容 的 缓冲 区 ， 主 要 用 于 接收 


HTTP 头 部 


ngx buf t *header in; 





/*ngx_http process request headers 方 法 在 接收 、 解 析 完 
HTTP 请 求 的 头 部 后 ， 会 把 解析 完 的 每 一 个 
HTTP 头 部 加 入 到 
headers in 的 
headers 链 表 中 ， 同 时 会 构造 
headers in 中 的 其 他 成 员 
六 
ngx http headers in t headers in; 


/*HTTP 模 块 会 把 想 要 发 送 的 


TiNNinNnnn http://wWwWw linuxorobe.con 





HTTP 响 应 信息 放 到 


headers out 中 ， 期 望 


HTTP 框 架 将 


headers out 中 的 成 员 序 列 化 为 


HTTP 响 应 包 发 送 给 用 户 


4 


ngx http headers out t headers out; // 接收 


HTTP 请 求 中 包 体 的 数据 结构 ， 详 见 


11.8 节 


ngx http request boqy 七 *request body; // 延迟 关闭 连接 的 时 间 


time t lingering time; 


/* 当 前 请 求 初始 化 时 的 时 间 。 


start_sec 是 格林 威 治 时 间 


1970 年 





0 分 


0 和 到 形 下 吕 同名 此 长 [村 时 棋 全 证 后 在 习 下] "下去 二 yt 才 :9: AA 让 凤 Xhn eBexCcon 








TCP 连 接 后 ， 第 一 次 接收 到 可 读 事件 时 的 时 间 





人 
time t start sec; 
// 与 
start sec 配 合 使 用 ， 表 示 相 对 于 
start_set 秒 的 毫秒 偏 移 量 
ngx msec t start msec; 
/* 以 下 
9 个 成 员 都 是 
ngx http process request line 方 法 在 接收 、 解 析 
HTTP 请 求 行 时 解析 出 的 信息 ， 其 意义 在 第 
3 章 已 经 详细 描述 过 ， 这 里 不 再 介绍 
4 


ngx uint t methog; 

ngx uint t http version; 
ngx str t request line; 
ngx str t uri; 

ngx_ str 七 args; 


ngx str 七 exten; 
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ngx str 七 unparsed uri; 
ngx_ str t method name; 


ngx_ str t http protocol; 


HITP 响 应 。 
out 中 保存 着 由 
headers _ out 中 序列 化 后 的 表示 
HTTP 头 部 的 
TCP 流 。 在 调用 
ngx _ http output filter 方 法 后 ， 
out 中 还 会 保存 待 发 送 的 
HTTP 包 体 ， 它 是 实现 异步 发 送 
HTTP 响 应 的 关键 ， 参 见 
I, 信 节 
*/ 
ngx chain 七 *out; 
/* 当 前 请 求 既 可 能 是 用 户 发 来 的 请 求 ， 也 可 能 是 派生 出 的 子 请 求 ， 而 
main 则 标识 一 系列 相关 的 派生 子 请 求 的 原始 请 求 ， 我 们 一 般 可 通过 


main 和 当前 请 求 的 地 址 是 否 相 等 来 判断 当前 请 求 是 否 为 用 户 发 来 的 原始 请 求 
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ngx http request 七 *main; 


// 当前 请 求 的 父 请 求 。 注 意 ， 父 请 求 未 必 是 原始 请 求 


ngx http request 七 *parent; 


/* 与 


subrequest 子 请 求 相 关 的 功能 。 在 


11.10.6 节 中 会 看 到 它们 在 


HTTP 框 架 中 的 部 分 使 用 方式 


4 


ngx http postponed request t *postponed; ngx http post subrequest t *post subrequest; /* 所 有 的 子 请 求 都 是 通过 


posteqd requests 这 个 单 链表 来 链接 起 来 的 ， 执 行 


post 子 请 求 时 调用 的 


ngx http run posted requests 方 法 就 是 通过 遍历 该 单 链表 来 执行 子 请 求 的 





* 


ngx http posted request t *posted requests; /* 全 局 的 


ngx http phase engine 七 结构 体 中 定义 了 一 个 





ngx http phase handler 七 回调 方法 组 成 的 数组 ， 而 
Phase _ handqler 成 员 则 与 该 数组 配合 使 用 ， 表 示 请 求 下 次 应 当 执 行 以 
phase handler 作 为 序号 指定 的 数组 中 的 回调 方法 。 


HTTP 框 架 正 是 以 这 种 方式 把 各 个 
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HTTP 模 块 集成 起 来 处 理 请 求 的 


人 


ngx_int t phase handler; 


/* 表 示 








NGX_HTTP_ CONTENT _ PHASE 阶段 提供 给 


HTTP 模 块 处 理 请 求 的 一 种 方式 ， 


content handler 指 向 


HTTP 模 块 实现 的 请 求 处 理 方法 ， 详 见 


11.6.4 节 


ngx http handler pt content handler; /* 在 





NGX_HTTP_ACCESS_PHASE 阶 段 需要 判断 请 求 是 否 具有 访问 权限 时 ， 通 过 





access_ code 来 传递 
HTTP 模 块 的 
handler 回 调 方法 的 返回 值 ， 如 果 
access code 为 
0， 则 表示 请 求 具备 访问 权限 ， 反 之 则 说 明 请 求 不 具备 访问 权限 
Ry 


ngx uint t access code; 


全 他 从 计生 守 Nn http:/ /waw | i nuxorobe. con 





HTTP 包 体 


off t request length; 
/* 在 这 个 请 求 中 如 果 打开 了 某 些 资源 ， 并 需要 在 请 求 结束 时 释放 ， 那 么 都 需要 在 把 定义 的 释放 资源 方法 添加 到 
cleanup 成 员 中 ， 详 见 
11.10.2 节 
*/ 
ngx http cleanup t *cleanup; 
/* 表 示 当 前 请 求 的 引用 次 数 。 例 如 ， 在 使 用 
subreduest 功 能 时 ， 依 附 在 这 个 请 求 上 的 子 请 求 数目 会 返回 到 
count 上 ， 每 增加 一 个 子 请 求 ， 
count 数 就 要 加 
1。 其 中 任何 一 个 子 请 求 派生 出 新 的 子 请 求 时 ， 对 应 的 原始 请 求 〈 
main 指 针 指 向 的 请 求 ) 的 
count 值 都 要 加 
1。 又 如 ， 当 我 们 接收 
HTTP 包 体 时 ， 由 于 这 也 是 一 个 异步 调用 ， 所 以 
count 上 也 需要 加 
1， 这 样 在 结束 请 求 时 ( 


11.10 节 中 介绍 ) ， 就 不 会 在 
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count 引 用 计数 未 清 零 时 销毁 请 求 。 可 以 参见 


11.10.3 节 的 


ngx http close _ request 方法 


*/ 


unsigned count:8; 


// 阻塞 标志 位 ， 目 前 仅 由 


aio 使 用 ， 本 章 不 涉及 


unsigned blocked:8; 


// 标志 位 ， 为 


1 时 表示 当前 请 求 正在 使 用 异步 文件 


工人 
unsigned aio:1; 
// 标志 位 ， 为 

1 时 表示 

URIL 发 生 过 





rewrite 重 写 


unsigned uri changed:1; 


/* 表 示 使 用 
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Di) 
加 


rewrite 重 


URL 的 次 数 。 因 为 目前 最 多 可 以 更 改 


10 淡 ; 所 到 


Uri changes 初 始 化 为 





和 | 


11; 而 每 重 


URL 一 次 就 把 


uri _ changes 减 


uri changes 等 于 


0， 则 向 用 户 返 回 失败 


*/ 
unsigned uri changes:4; 
/x 标 志 位 ， 为 
1 时 表示 当前 请 求 是 
keepalive 请 求 
*/ 


unsigned keepalive:1; 
/* 延 迟 关闭 标志 位 ， 为 
1 时 表示 需要 延迟 关闭 。 例 如 ， 在 接收 完 


HTTP 头 部 时 如 果 发 现 包 体 存在 ， 该 标志 位 会 设 为 
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1， 而 放弃 接收 包 体 时 则 会 设 为 


0， 参 见 
11.8 节 


*/ 
unsigned lingering close:1; 
// 标志 位 ， 为 
1 时 表示 正在 丢弃 


HTTP 请 求 中 的 包 体 


unsigned discard body:1; 


1 时 表示 请 求 的 当前 状态 是 在 做 内 部 跳 转 。 上 有 具体 用 法 可 参见 图 


11-5 中 的 第 


yy 


unsigned internal:1; 


1 时 表示 发 送 给 客户 端的 


HTTP 响 应 头 部 已 经 发 送 。 在 调用 
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ngx http send header 方 法 (参见 


11.9.1 节 ) 后 ， 若 已 经 成 功 地 启动 响应 头 部 发 送 流程 ， 该 标志 位 就 会 置 为 


1， 用 来 防止 反复 地 发 送 头 部 


人/ 


unsigned header sent:1; 


// 表示 缓冲 中 是 否 有 待 发 送 内 容 的 标志 位 


unsigned buffered:4; 


// 状态 机 解析 


HTTP 时 使 用 


state 来 表示 当前 的 解析 状态 


ngx uint t state; 








以 上 介绍 的 ngx_http_request_t 绪 构 体 成 员 ， 大 多 都 会 出 现在 本 章 后 续 章 节 中 ， 读 者 在 看 到 相应 的 变量 时 可 及 时 回 到 > 
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11.4 接收 HITP 请 求 行 


接收 HTTP 请 求 行 这 个 行为 必然 是 在 初始 化 请 求 之 后 发 生 的 。 在 图 11-2 的 第 11 步 表明 已 
经 调用 了 ngx_ http process_ request line 方 法 来 接收 HTTP 请 求 行 。HTTP 请 求 行 的 格式 如 下 所 


小 。 





GET uri HTTP1 .1 














可 以 看 出 ， 这 样 的 请 求 行 长 度 是 不 定 的 ， 它 与 URI 长 度 相关 ， 这 意味 着 在 读 事件 被 触发 
时 ， 内 核 套 接 字 缓 冲 区 的 大 小 未 必 足 够 接收 到 全 部 的 HTTP 请 求 行 ， 由 此 可 以 得 出 结论 : 调 
用 一 次 ngx_http_process_request line 方 法 不 一 定 能 够 做 完 这 项 工作 。 所 以 ， 
ngx_http_process_request_line 方 法 也 会 作为 读 事件 的 回调 方法 ， 它 可 能 会 被 epoll 这 个 事件 驱 
动机 制 多 次 调度 ， 反 复 地 接收 TCP 流 并 使 用 状态 机 解析 它们 ， 直 到 确认 接收 到 了 完整 的 
HTTP 请 求 行 ， 这 个 阶段 才 算 完成 ， 才 会 进入 下 一 个 阶段 接收 HTTP 头 部 。 





因此 ，ngx _http_process request line 方 法 与 ngx http_init connection 方 法 、 
ngx_http_init_ request{ 方 法 都 不 一 样 ， 后 两 种 方法 在 一 个 请 求 中 只 会 被 调用 一 次 ， 而 
ngx_http_process_request_line 方 法 则 至少 会 被 调用 一 次 ， 而 到 底 会 调用 多 少 次 则 取决 于 客户 
端的 行为 及 网 络 中 卫 包 的 转发 等 。 图 11-3 展 示 了 ngx http process_request line 方 法 的 流程 ， 需 
要 注意 其 中 对 各 个 步骤 的 描述 ， 其 中 有 些 步骤 会 导致 ngx_http_process_ request line 方 法 暂时 
结束 ， 但 会 在 下 一 次 读 事件 来 临时 继续 被 调用 。 





图 11-3 描 述 了 nsgx_http_ process request line 方 法 的 主要 流程 ， 由 于 它 涉及 了 TCP 字 符 流 的 
接收 、 解 析 ， 因 此 会 相对 复杂 一 些 ， 下 面 详细 描述 一 下 这 12 个 步 又 : 


1) 首先 检查 这 个 读 事件 是 否 已 经 超时 ， 超 时 时 间 仍 然 是 nginx.conf 配 置 文件 中 指定 的 
client header timeout。 如 果 ngx event t 事 件 的 timeout 标 志 为 1， 则 认为 接收 HTTP 请 求 已 经 超 
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时 ， 调 用 ngx http_close request 方 法 (参见 11.10.3 节 ) 关闭 请 求 ， 同 时 由 


ngx http process request line 方 法 中 返回 。 


2) 在 当前 读 事件 未 超时 的 情况 下 ， 检 查 header in 接收 缓冲 区 〈 参 见 图 11-2 的 第 6 步 ) 中 
是 否 还 有 未 解析 的 字符 流 。 第 一 次 调用 ngx http process tequest line 方 法 时 缓冲 区 里 必然 是 
空 的 ， 这 时 会 调用 封装 的 recv 方 法 把 Linux 内 核 套 接 字 缓冲 区 中 的 TCP 流 复制 到 header_ in 缓冲 
区 中 。header in 的 类 型 是 ngx_buf t， 它 的 pos 成 员 和 1last 成 员 指 辐 的 地 址 之 间 的 内 存 就 是 接收 
到 的 还 未 解析 的 字符 流 。 如 果 header in 接收 缓冲 区 中 还 有 未 解析 的 字符 流 ， 则 不 会 调用 recv 
方法 接收 ， 而 是 跳 到 下 面 的 第 4 步 继 续 执行 。 





3) 在 第 2 步 中 曾经 调用 封装 的 recv 方 法 ， 如 采 返 回 值 表 示 连 接 出 现 错 误 或 者 客户 端 已 经 
关闭 连接 ， 则 跳 转 到 第 1 步 ， 如 果 返 回 值 表示 接收 到 客户 站 发 送 的 字符 流 ， 则 跳 转 到 第 5 步 中 
解析 :如 果 返 回 值 表 示 本 次 没有 接收 到 TCP 流 ， 需 要 继续 检测 这 个 读 事件 ， 则 开始 本 步骤 的 
执行 。 

首先 检查 这 个 读 事件 是 否 在 定时 器 中 ， 如 采 已 经 在 定时 器 ， 则 跳 转 到 第 4 步 ， 反之， 调 
用 ngx_add_timer 方 法 回 定 时 器 添加 这 个 读 事 件 。 


4) 调用 ngx_handle_read_event 方 法 把 该 读 事 件 添加 a 到 epoll 中 ， 同 时 
ngx http_ process request line 方 法 结 
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[检查 是 否 接收 HTTP 请 求 超时 ] 














[没有 超时 ] 


[接收 缓冲 区 中 没有 未 解析 的 数据 ] 
ne 

接收 TCP 流 
[检查 接收 方法 的 返回 值 





[ 读 缓冲 区 仍 有 空闲 ] 
[接收 缓冲 区 在 还 有 
未 解析 的 数据 ] 

| 
[连接 错误 或 客户 端 关 闭 连 接 ] 
[ 读 事 件 没有 在 定时 器 中 ] 


\ 
3) 将 读 事 件 添加 
到 定时 器 中 








[ 读 事 件 已 经 存在 于 定时 器 中 ] 4) 将 读 事 件 添加 
到 jepoll 

5) 用 状态 机 解析 已 接收 

到 的 字符 流 

[检查 状态 机 的 返回 值 ] 

[需要 继续 接收 数据 ] 


[ 读 缓 闹 区 用 完 ] [解析 得 到 请 求 line] 





[解析 失败 ] 






Wa 


1) 调 用 ngx_http_close-_ request 





[HTTP 1.0 版 本 以 下 ] 


[HTTP10 或 者 HTTP1.1 版 本 ] 






10) 初始 化 存放 HTTP 
头 部 的 容器 





8 ) 找 到 请 求 对 应 


server 


的 
Ds 


C2 
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图 11-3 接收、 解析 HTIP 请 求 行 的 流程 图 


5) 在 第 2 步 接收 到 字符 流 后 ， 将 在 这 一 步 又 用 状态 机 解析 已 经 接收 到 的 TCP 字 符 流 ， 确 
认 其 是 否 构 成 完整 的 HTTP 请 求 行 。 这 个 状态 机 解析 请 求 行 的 方法 叫做 
ngx_http_parse_ request line， 它 使 用 ngx_http_request t 结 构 体 中 的 state 成 员 来 保存 解析 状态 ， 
如 下 所 示 。 





ngx _ int t ngx http parse request line(ngx httpP request t r, ngx buf t b) 











这 里 传 入 的 参数 b 是 header_in 绥 冲 区 ， 返 回 值 主要 有 3 类 : 返回 NGX_OK 表 示 成 功 地 解析 
到 完整 的 HTTP 请 求 行 ， 返回 NGX_AGAIN 表 示 目 前 接收 到 的 字符 流 不 足以 构成 完成 的 请 求 
行 ， 还 需要 接收 更 多 的 字符 流 ; 返回 NGX _ HTTP PARSE INVALID REQUEST 或 者 
NGX HTTP PARSE INVALID 09 METHOD 等 其 他 值 时 表示 接收 到 非法 的 请 求 行 。 


6) 如 果 ngx _http parse_ request line 方 法 返回 NGX_OK， 表 示 成 功 地 接收 到 完整 的 请 求 
行 ， 这 时 跳 转 到 第 7 步 继续 执行 。 


如 果 nex http parse request line 方 法 返回 NGX AGAIN， 则 表示 需要 接收 更 多 的 字符 流 ， 
这 时 需要 对 header in 缓冲 区 做 判断 ， 检 查 是 否 还 有 空闲 的 内 存 ， 如 果 还 有 未 使 用 的 内 存 可 以 
继续 接收 字符 流 ， 则 跳 转 到 第 2 步 ， 检 查 缓冲 区 是 否 有 未 解析 的 字符 流 ， 否 则 调用 
ngx_http_alloc_large_header_buffer 方 法 分 配 更 大 的 接收 缓冲 区 。 到 底 分 配 多 大 呢 ? 这 由 
nginx.conf 文 件 中 的 large_client header buffers 配 置 项 指定 。 





如 果 ngx http parse request line 方 法 返回 NGX HTTP PARSE INVALID REQUEST 或 者 
NGX _ HTTP PARSE INVALID 09 METHOD 等 其 他 值 ， 那 么 HTTP 框 架 将 不 再 处 理 非法 请 
求 ， 跳 转 到 第 1 步 关 闭 请 求 。 








7) 在 接收 到 完整 的 HITP 请 求 行 后 ， 首 先 要 把 请 求 行 中 的 信息 如 方法 名 、URI 及 其 参 
数 、HTTP 版 本 等 信息 设置 到 ngx http request t 结 构 体 的 相应 成 员 中 (如 request line、uri、 
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method name、unparsed_uri、http_protocol、exten、args 等 ) ， 在 3.6.2 节 开发 HTTP 模块 时 曾 介 
绍 过 这 些 成 员 的 用 法 ， 它 们 就 是 在 这 一 步 中 被 赋值 的 。 





8) 如 果 在 第 7 步 得 到 的 http_version 成 员 中 显示 用 户 请 求 的 HTTP 版 本 小 于 1.0〈 如 HTTP 
0.9 版 本 ) ， 其 处 理 过 程 将 与 HTTP 1.0 和 HTTP 1.1 的 完全 不 同 ， 它 不 会 有 接收 HTTP 头 部 这 一 
步骤 。 这 时 将 会 调用 ngx http_ find virtual server 方 法 寻找 到 相应 的 虚拟 主机 ， 回 顾 一 下 在 
10.4 节 中 虚拟 主机 是 使 用 散 列 表 来 进行 管理 的 ，ngx _http_find virtual server 方 法 就 是 用 于 在 
散 列表 中 检索 出 虚拟 主机 。 





如 果 http_version 成 员 中 显示 出 用 户 请 求 的 HTTP 版 本 是 1.0 或 者 更 高 的 版 本 ， 则 直接 跳 到 
第 10 步 中 执行 。 


9) 继续 处 理 HTTP 版 本 小 于 1.0 的 情形 。 由 于 不 需要 再 次 接收 HTTP 头 部 ， 调 用 
ngx_http_process_fequest 方 法 开始 处 理 请 求 〈 参 见 11.6 节 ) 。 


10) 初始 化 ngx http_ request t 绪 构 体 中 存放 HTTP 头 部 的 一 些 容器 ， 如 headers_ in 结构 体 中 
ngx_list t 类 型 的 headers 链 表 容 器 、ngx_array t 类 型 的 cookies 动 态 数组 容器 等 ， 为 下 一 步 接 收 
HTTP 头 部 做 好 准备 《参见 11.5 节 ) 。 


11) 由 于 已 经 接收 完 HTTP 请 求 行 ， 因 此 这 时 把 读 事件 的 回调 方法 由 
ngx http process request line 改 为 ngx http process request headers， 准 备 接收 HTTP 头 部 。 


12) 调用 ngx http process request headers 方 法 开始 接收 HTTP 头 部 。 


接收 完 HITP 请 求 行 后 ， 在 下 一 节 中 我 们 将 分 析 接 收 HTTP 头 部 这 一 步骤 。 
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11.$ 接收 HITP 头 部 


本 节 将 描述 接收 HTTP 头 部 这 一 阶段 ， 该 阶段 是 通过 ngx http process request headers 方 
法 实现 的 ， 该 方法 将 被 设置 为 连接 的 读 事件 回调 方法 ， 在 接收 较 大 的 HITP 头 部 时 ， 它 有 可 
能 会 被 反复 多 次 地 调用 。HTTP 头 部 类 似 下 面 加 了 下 划 线 的 字符 串 ， 而 
ngx_http_process_Tequest_headers 方 法 的 目的 就 在 于 接收 到 当前 请 求全 部 的 HITP 头 部 。 











GET uri HTTPL.1 
Cred: XXX 
username: ttt 
content-length: 4 
test 














可 以 看 出 ，HTITP 头 部 也 属于 可 变 长 度 的 字符 串 ， 它 与 HTTP 请 求 行 和 包 体 间 都 是 通过 换 
行 符 来 区 分 的 。 同 时 ， 它 与 解析 HTTP 请 求 行 一 样 ， 都 需要 使 用 状态 机 来 解析 数据 。 既 然 
HTTP 请 求 行 和 头 部 都 是 变 长 的 ， 对 它们 的 总 长 度 当 然 是 有 限制 的 。 从 图 11-3 的 第 6 步 可 以 看 
出 ， 当 最 初 分 配 的 大 小 为 client header buffer size 的 缓冲 区 且 无 法 容纳 下 完整 的 HTTP 请 求 行 
或 者 头 部 时 ， 会 再 次 分 配 大 小 为 large_client header buffers (这 两 个 值 沸 ee 
定 的 配置 项 ) 的 缓冲 区 ， 同 时 会 将 原先 缓冲 区 的 内 容 复制 到 新 的 缓冲 区 中 。 所 以 ， 这 意味 着 
可 变 长 度 的 HITP 请 求 行 加 上 HTTP 头 部 的 长 度 总 和 不 能 超过 large_client header_ buffers 指 定 的 
字 节 数 ， 和 否则 Nginx 将 会 报错 。 








先 来 看 看 图 11-4 中 展示 的 HTTP 框 架 使 用 ngx http process request headers 方 法 接收 、 解 析 


HTTP 头 部 的 流程 。 





图 11-4 中 分 支 较 多 ， 下 面 详 细 地 解释 一 下 图 中 的 11 个 步骤 。 


1) 如 同 接收 http 请 求 行 一 样 ， 首 先 检 查 当 前 的 读 事件 是 否 已 经 超时 。 检 查 方法 仍然 是 检 
查 事件 的 timeout 标 志 位 ， 如 果 为 1， 则 表示 接收 请 求 已 经 超时 ， 这 时 调用 


ngx http close request 方 法 关闭 连接 ， pr ES http process Pe headers 方 法 。 
让 让 站 让 全 六 站 放 A bo 





2) 检查 接收 HTTP 请 求 头 部 的 header_in 绥 冲 区 是 否 用 尽 ， 当 header in 绥 冲 区 的 pos 成 员 指 
同 了 end 成 员 时 ， 表 示 已 经 用 尽 ， 这 时 需要 调用 ngx http alloc large header buffer 方 法 分 配 更 
大 、 更 多 的 缓冲 区 ， 如 同 图 11-3 中 的 第 6 步 。 如 宁 缓 冲 区 还 没有 用 尽 ， 则 跳 到 第 4 步 中 执行 





3) 事实 上 ，ngx http alloc large header buffer 方 法 会 有 3 种 返回 值 ， 其 中 NGX OK 表示 
成 功 分 配 到 更 大 的 缓冲 区 ， 可 以 继续 接收 客户 端 肥 来 的 字符 流 ， NGX_DECLINED 表 示 已 经 
达到 缓冲 区 大 小 的 上 限 ， 无 法 分 配 更 大 的 缓冲 区 ;NGX_ERROR 表 示 出 现 错误 。 所 以 ， 当 返 
回 NGX ERROR 时 ， 跳 转 到 第 1 步 执行 ， 而 当 返 回 NGX DECLINED 时 ， 需 要 向 用 户 返 回 错误 
并 且 同 时 退出 ngx http process request headers 方 法 ， 错 误 码 由 安 
NGX _ HTTP REQUEST HEADER TOO _ LARGE 表示 ， 也 就 是 494， 实 际 上 这 一 过 程 是 通过 调 
用 ngx_ http finalize _ request 方法 来 实现 的 《参见 11.10.6 节 ) ;如果 返回 NGX OK， 则 继续 第 4 








步 执行 。 
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[header in 缓冲 区 已 经 用 尽 ] 


[已 经 超时 ] 






本 


分 配 更 天 
} 配 更 7 





3) 向 客户 端 发 送 
494 响 应 并 结束 请 求 







[需要 继续 接收 才能 解析 ] 
[连接 错误 或 用 户 关闭 连接 ] 
[ 震 要 继续 接收 数据 ] 





[检查 recv 方 法 返回 值 ] 


XX 


[接收 到 新 数据 ] 5) 将 读 事 件 添 加 到 


定时 器 与 epoll 中 













6) 用 状态 机 解析 已 接收 
到 的 字符 流 






[检查 状态 机 返回 值 ] 










7 ) 设置 解析 出 
的 头 音 









[解析 到 一 行 HTTP 头 部 ] 





[解析 失败 ] 


9 解析 完 HTTP 头 部 ] 












9) hos | 
根据 hest 头 部 找到 





1) 调 用 ngx_http_close_request 
关闭 请 求 







10) 检查 部 分 头 首 
信息 是 否 合法 


11) 调 用 ngx_http_ process_request 
方法 处 理 请 求 






图 11-4 ngx_http_process_request_headers 方 法 接收 HTTP 头 部 的 流程 图 
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4) 接收 客户 端 发 来 的 字符 流 ， 即 把 内 核 套 接 字 缓 冲 区 上 的 字符 流 接收 到 header in 缓冲 
区 中 。 这 一 过 程 是 通过 调用 封装 过 的 recv 方 法 实现 的 ， 如 果 过 程 中 出 现 错误 ， 仍 然 跳 转 到 第 
1 步 执 行 ， 如果 没有 接收 到 数据 ， 但 错误 码 表 明 仍然 需要 再 次 接收 数据 ， 则 跳 转 到 第 5 步 执 
行 ; 如 宁 成 功 接 收 到 数据 ， 则 路 转 到 第 6 步 执行 。 











5) 这 个 步骤 将 该 读 事 件 谎 加 到 epoll 和 定时 器 中 ， 实 际 上 就 是 图 11-3 中 第 3 步 和 第 4 步 的 
合并 ， 不 再 玖 述 。 


6) 调用 ngx_http_parse_header_ line 方 法 解析 缓冲 区 中 的 字符 流 。 这 种 方法 有 3 个 返回 值 : 
返回 NGX_OK 时 ， 表 示 解 析出 一 行 HTTP 头 部 ， 这 时 需要 跳 转 到 第 7 步 设 置 这 行 已 经 解析 出 的 
HTTP 头 部 ， 返 回 NGX_HTTP PARSE HEADER DONE 时， 表示 已 经 解析 出 了 完整 的 HTTP 头 
部 ， 这 时 可 以 准备 开始 处 理 HTTP 请 求 了 (11.6 节 介绍 ) ; 返回 NGX AGAIN 时 ， 表 示 还 需要 
接收 到 更 多 的 字符 流 才能 继续 解析 ， 这 时 需要 跳 转 到 第 2 步 去 接收 更 多 的 字符 流 ， 除 此 之 外 
的 错误 情况 ， 将 跳 转 到 第 8 步 发 送 400 错 误 给 客户 端 。 


7) 将 解析 出 的 HTTP 头 部 设置 到 表示 ngx http request t 结 构 体 headers in 成 员 的 headers 链 
表 中 。 从 3.6.3 节 中 可 以 看 出 ， 开 发 HTTP 模 块 时 获取 到 的 HITP 头 部 融 是 在 这 个 步骤 中 设置 
的 。 


8) 当 调 用 ngx_http_parse_header line 方 法 解析 字符 串 构成 的 HTTP 时， 是 有 可 能 遇 到 非法 
的 或 者 Nginx 当 前 版 本 不 文 持 的 HITP 头 部 的 ， 这 时 该 方法 会 返回 错误 ， 于 是 调用 
ngx_http finalize request 方 法 ， 向 客户 端 发 送 NGX _ HTTP BAD REQUEST 宏 对 应 的 400 错 误 码 
啊 应 。 





9) 当 ngx_http_parse_header line 方 法 认为 已 经 解析 到 完整 的 HTTP 头 部 时 ， 将 会 根据 
HTTP 头 部 中 的 host 字 段 情况 ， 调 用 nex http find virtual server 方 法 找到 对 应 的 虚拟 主机 配置 
块 ， 也 就 是 第 10 章 中 介绍 过 的 ngx http core srv_conf t 结 构 体 。 这 一 步 会 导致 图 11-2 的 第 4 步 
中 ngx_http_request t 结 构 体 里 的 srv_conf、loc_conf 成 员 被 重新 设置 ， 以 指向 正确 的 虚拟 主 
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10) 这 一 步骤 将 检查 以 上 步骤 中 接收 解析 出 的 HITP 头 部 是 否 合法 ， 主 要 包括 以 下 几 
:如 果 HTTP 版 本 为 1.1， 则 host 头 部 不 可 以 为 空 ， 否 则 返回 400 Bad Request 错 误 啊 应 给 客户 
端 ; 如 果 传 递 了 Content-Length 头 部 ， 那 么 它 必 须 是 合法 的 数字 ， 人 否则 会 返回 400 Length 
Required 错 误 响 应 给 客户 端 ;， 如 采 请 求 使 用 了 PUT 方法 ， 那 么 必须 传递 Content-Length 头 部 ， 
否则 会 返回 400 Length Required 错 误 响 应 给 客户 端 。 


演 


11) 调用 ngx http process reques 人 方法 开始 使 用 各 HTTP 模 块 正式 地 在 业务 上 处 理 HTTP 请 





以 上 11 步 又 仅 专 注 于 接收 并 解析 出 全 部 的 HITP 头 部 ， 同 时 检查 它们 的 合法 性 ， 并 将 解 
析出 的 HITP 头 部 设置 到 ngx_http request t 结 构 体 里 的 合适 位 置 。 接 下 来 开始 讨论 如 何 使 用 以 
上 两 节 中 已 经 解析 好 的 HTTP 请 求 行 和 头 部 。 
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11.6 ”处 理 HTTP 请 求 


在 接收 到 完整 的 HITP 头 部 后 ， 已 经 拥有 足够 的 必要 信息 开始 在 业务 上 处 理 HITP 请 求 
了 。 本 市 将 说 明 HTTP 框 架 是 如 何 召 集 负 员 具 体 功 能 的 各 HTTP 模 块 合作 处 理 请 求 的 。 在 图 
11-4 的 第 11 步 及 图 11-3 的 第 10 步 中 ， 最 后 都 是 通过 调用 ngx_http_process_request 方 法 开始 处 理 














请 求 ， 本 节 将 讨论 ngx_http_process_request 方 法 的 流程 ， 而 且 ngx_http_process_request 方 法 只 

是 处 理 请 求 的 开始 ， 对 于 基于 事件 驱动 的 异步 HTTP 框 架 来 说 ， 处 理 请求 并 不 是 一 步 可 以 完 

成 的 ， 所 以 我 们 也 会 讨论 后 续 TCP 连 接 上 的 回调 方法 ngx_http_request_handler 的 流程 。 首 先 来 
看 看 接收 完了 ETTP 头 部 后 ngx http process_request 方 法 所 做 的 事情 ， 如 图 11-5 所 示 。 
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[检查 TCP 本 









1) 把 读 事件 从 
定时 一 中 移 除 


2) 重新 设置 连接 上 
读 / 写 事件 的 处 理 方法 










3 ) 设置 请 求 的 
read_event_handler 方 法 
[检查 请 求 的 internal 标志 位 ] 


[internal 为 1] 


4) 设置 phase_handler 序 号 为 





server_rewrite_index 


[internal 为 0] 


5 ) 设 置 请 求 的 
phase_handler 序 号 为 0 


6) 设置 请 求 的 write event handler 


调 方法 


7) 调用 ngx_http_core_run_phases 
方法 集成 HTTP 模 块 处 理 请 求 


8 ) 调 用 ngx_http_run_posted_requests 


方法 执行 post 请 求 





名 
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图 11-5 ”ngx_http_process_request 处 理 HTTP 请 求 的 流程 图 


下 面 详细 介绍 图 11-5 中 的 8 个 步 又。 





1) 由 于 现在 已 经 开始 准备 调用 各 HTTP 模 块 处 理 请 求 了 ， 因 此 不 再 存在 接收 HTTP 请 求 
头 部 超时 的 问题 ， 那 就 需要 从 定时 上 费 中 把 当前 连接 的 读 事件 移 除 了 。 检 查 读 事件 对 应 的 
timer_ set 标志 位 ， 为 1 时 表示 读 事 件 已 经 添加 到 定时 器 中 了 ， 这 时 再 要 调用 ngx_del timer 从 定 
时 器 中 移 除 读 事件 ， 如 果 timer_set 标 志 位 为 0， 则 直接 执行 第 2 步 。 











2) 从 现在 开始 不 会 再 需要 接收 HTTP 请 求 行 或 者 头 部 ， 所 以 需要 重新 设置 当前 连接 读 / 
写 事件 的 回调 方法 。 在 这 一 步骤 中 ， 将 同时 把 读 事件 、 写 事件 的 回调 方法 都 设置 为 
ngx_http_ request _handler 方 法 ， 在 下 面 的 图 11-7 中 会 介绍 到 这 个 方法 ， 请 求 的 后 续 处 理 都 是 通 
过 ngx http _ request handler 方 法 进行 的 。 





3) 设置 ngx_ http request t 结 构 体 的 read event handler 方 法 为 ngx http block reading。 前 面 
11.3 节 中 曾 介 绍 过 read_event handler 方 法 ， 当 再 次 有 读 事 件 到 来 时 ， 将 会 调用 
read event handler 方 法 处 理 请 求 。 而 这 里 将 它 设置 为 ngx http_ block reading 方 法 ， 这 个 方法 
可 认为 不 做 任何 事 ， 它 的 意义 在 于 ， 目 前 已 经 开始 处 理 HTTP 请 求 ， 除 非 茶 个 HTTP 模 块 重新 
设置 了 read_event handler 方 法 ， 否 则 任何 读 事件 都 将 得 不 到 处 理 ， 也 可 以 认为 读 事 件 被 阻塞 
忆 








4) 检查 ngx_http_request t 结 构 体 的 internal 标 志 位 ， 如 果 internal 为 0， 则 继续 执行 第 5 步 ，; 
如 果 internal 标 志 位 为 1， 则 表示 请 求 当前 需要 做 内 部 跳 转 ， 将 要 把 结构 体 中 的 phase_handler 
序号 置 为 Server rewrite index。 先 来 回顾 一 下 10.6.1 节 ， 注 意 ngx http phase engine t 结 构 体 中 
的 handlers 动 态 数组 中 保存 了 请 求 需 要 经 历 的 所 有 回调 方法 ， 而 server rewrite index 则 是 
handlers 数 组 中 NGX HTTP SERVER REWRITE PHASE 处 理 阶 段 的 第 一 个 





ngx_http_ phase _ handler t 回 调 方法 所 处 的 位 置 。 


可 tps 和 和 全 守 个 人 四 鸣 响 下 和 生字 站 eC 





phase handler 序 号 使 用 ， 由 phase handler 指 定 着 请 求 将 要 执行 的 handlers 数 组 中 的 方法 位 置 。 
注意 ，handlers 数 组 中 的 方法 都 是 由 各 个 HTTP 模 块 实 现 的 ， 这 就 是 所 有 HTTP 模 块 能 够 共同 
处 理 请 求 的 原因 。 





在 这 一 步骤 中 ， 把 phase handler 序 号 设 为 server rewrite index， 这 意味 着 无 论 之 前 执行 
到 哪 一 个 阶段 ， 马 上 都 要 重新 从 NGX _ HTTP SERVER REWRITE PHASE 阶 段 开始 再 次 执 
行 ， 这 是 Nginx 的 请 求 可 以 反复 rewrite 重 定 癌 的 基础 。 


5) 当 internal 标 志 位 为 0 时 ， 表 示 不 需要 重 定向 《如 刚 开 始 处 理 请 求 时 ) ， 将 
phase handler 序 号 置 为 0， 意 味 着 从 ngx http phase engine t 指 定数 组 的 第 一 个 回调 方法 开始 执 
行 〈《 参 见 10.6 节 ， 了 解 ngx_http_phase_engine t 是 如 何 将 各 HTTP 模 块 的 回调 方法 构造 成 
handlers 数 组 的 ) 。 





6) 设置 ngx http request ft 结构 体 的 write_ event handler 成 员 为 ngx http core _ run phases 方 
法 。 如 同 read_event handler 方 法 一 样 ， 在 图 11-7 中 可 以 看 到 write event handler 方 法 是 如 何 被 
调用 的 。 


7) 执行 ngx http core run phases 方 法 ， 其 流程 如 图 11-6 所 示 。 
8) 调用 ngx http run posted requests 方 法 执行 post 请 求 ， 参 见 11.7 节 。 


上 述 第 7 步调 用 了 ngx_http_core_run phases 方 法 ， 该 方法 将 开始 调用 各 个 HTTP 模 块 共同 
处 理 请 求 。 在 第 10 章 我 们 讨论 过 HTTP 框 架 的 初始 化 ， 在 这 一 过 程 中 是 允许 各 个 HTTP 模 块 将 
目 己 的 处 理 方法 按照 11 个 ngx_http_phases 阶 段 添 加 到 全 局 的 ngx_http_core main conf tt 结构 体 
中 的 。 下 面 简单 地 回顾 一 下 它 的 定义 ， 如 下 所 示 。 








typedef struct { 


// HTTP 框 架 初始 化 后 各 个 


are 徘 丫 二 引 * 下 于 下 9 和 站 站 站 由 由 Phttp:/wNwv Tinuxorobe. con 





phase engine 

ngx http phase engine t phase engine; 
} ngx http core main conf t; 
typedef struct { 

/* 由 








ngx_http_phase handler 七 结构 体 构成 的 数组 ， 每 一 个 数组 成 员 代 表 着 一 个 


HTTP 模 块 所 添加 的 一 个 处 理 方法 


ngx http phase handler t handlers; 


} ngx http Phase engine t; 
typedef struct ngx http phase handler s ngx http phase handler t; 
struct ngx http phase handler s { 

/海外 








handler 方 法 必须 对 应 着 一 个 
checker 方 法 ， 这 个 
checker 方 法 由 
HTTP 框 架 实现 


了 
ngx _ http phase handler pt checker; 
// 各 个 


HTTP 模 块 实现 的 方法 


ngx http handler pt handler; 





可 以 看 到 ， 根 据 ngx http core main conf t 结 构 体 的 phase engine 成 员 即 可 依次 调用 各 个 
HTTP 模 块 来 共同 处 理 一 个 请 求 。 下 面 看 看 图 11-6 中 展示 的 ngx_http_core run phases 方 法 的 流 


程 。 
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是 否 实 现 厂 checke 方法 | 







| 实现 checker 方法 | 










执行 phase_handler 序 号 指定 的 


[返回 
checker 方法 


:NGX_OK] 


[未 实现 checker 方 法 | “| 检查 check 方法 返回 值 | 


| checker 方 法 返回 NMGX_ OK| 





图 11-6 ”ngx_http_core_run_phases 方 法 的 执行 流程 


在 图 11-6 中 仅 会 执行 每 个 nex http phase handler t 处 理 阶段 的 checker 方 法 ， 而 不 会 执行 
handler 方 法 ， 其 原因 已 在 10.6 节 讲 过 ， 这 是 因为 handler 方 法 其 实 仅 能 在 checker 方 法 中 被 调 
用 ， 而 且 checker 方 法 由 HTTP 框 架 实现 ， 所 以 可 以 控制 各 HTTP 模 块 实现 的 处 理 方 法 在 不 同 的 
阶段 中 采用 不 同 的 调用 行为 。 再 来 简单 地 看 一 下 调用 的 源 代码 。 








void ngx http core run phases(ngx http request 七 *r) 
{ 
ngx int t re; 
ngx http phase handler t ph; 
ngx http core main conf t cmcef; 
cmcf = ngx http get module main conf(r, ngx http core module); 
ph = cmcf->phase engine.handlers; 
while (ph[lr->phase handler].checker) { 
rc = phlr->phase handler]l .checker(r, &phlr->phase handler]); 
if. (EG: ==" NGX OK) { 
return; 
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可 以 看 到 ，ngx http_ request t 结 构 体 中 的 phase handler 成 员 将 决定 执行 到 哪 一 阶段 ， 以 及 
下 一 阶段 应 当 执 行 哪个 HTTP 模 块 实现 的 内 容 。 在 图 11-5 的 第 4 步 和 第 5 步 中 可 以 看 到 请 求 的 
phase_ handler 成 员 会 被 重 置 ， 而 HITP 框 架 实 现 的 checker 方 法 也 会 修改 phase_ handler 成 员 的 
值 。 表 11-1 列 出 了 HTTP 框 架 实 现 的 所 有 checker 方 法 ， 如 下 所 示 。 





表 11-1 HTIP 框 架 为 11 个 阶段 实现 的 checkert 方 法 


阶段 名 称 
NGX HTTP POST READ PHASE 


NGX HTTP SERVER REWRITE PHASE 
NGX HTTP FIND CONFIG PHASE 
NGX HTTP REWRITE PHASE 

NGX HTTP POST REWRITE PHASE 


NGX HTTP PREACCESS PHASE 
NGX HTTP ACCESS PHASE 


NGX HTTP POST ACCESS PHASE 


NGX HTTP TRY FILES PHASE 
NGX HTTP CONTENT PHASE 
NGX HTTP LOG PHASE 


checker 方法 

ngx http core generic phase 
ngx http core rewrite phase 
ngx http_core find config phase 
ngx http_ core rewrite phase 
ngx http core post rewrite phase 
ngx http core generic phase 
ngx http_ core access phase 

ngx http core post access phase 
ngx http core try files phase 
ngx http_ core content phase 


ngx http core generic phase 








我 们 在 10.6 节 中 曾经 详细 介绍 过 HTTP 阶 段 。 在 11 个 阶段 中 其 中 7 个 是 允许 各 个 HTTP 模 块 
向 阶段 中 任意 添加 自己 实现 的 handler 处 理 方法 的 ， 但 同一 个 阶段 中 的 所 有 handler 处 理 方法 都 
拥有 相同 的 checker 方 法 ， 见 表 11-1。 我 们 知道 ， 每 个 阶段 中 处 理 方 法 的 返回 值 都 会 以 不 同 的 
方式 影响 HTTP 框 架 的 行为 ， 而 在 图 11-6 中 也 可 以 看 到 ，checker 方 法 在 返回 NGX_OK 和 其 他 
值 时 也 会 导致 不 同 的 结果 (每 个 checker 方 法 的 返回 值 实际 上 与 handler 处 理 方法 的 返回 是 相关 
的 ， 参 见 10.6.2 节 ~10.6.12 节 中 对 各 个 阶段 的 说 明 ) 。 当 checker 方 法 的 返回 值 非 NGX_OK 时 ， 
意味 着 向 下 执行 phase_engine 中 的 各 处 理 方法 ， 反 之， 当 任何 一 个 checker 方 法 返回 NGX_OK 
时 ， 意 味 着 把 控制 权 交 还 给 Nginx 的 事件 模块 ， 由 它 根 据 事 件 (网络 事件 、 定 时 器 事件 、 异 











步 /O 事 件 等 ) 再 次 调度 请 求 。 然 而 ， 








个 请 求 多 半 需 要 Nginx 事 件 模块 多 次 地 调度 HITP 模 块 


处 理 ， 这 时 就 要 看 在 图 11-$ 中 第 2 步 设 置 的 读 / 写 事 件 的 回调 方法 ngx_ http request handler 的 功 
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1) 由 触发 事件 中 取出 





ngx_http _request_t 结 构 体 
[检查 当前 事件 是 可 读 事 件 还 是 可 写 事 件 ] 


[ 当前 事件 可 读 ] ”[ 当 前 事件 可 写 ] 






2 ) 执 行 write_event handler 方 法 





3 ) 执行 read_event_handler 方 法 


4 ) 调用 ngx http_run_posted_requests 方法 执行 post 请 求 





po a ea fa TRY 





图 11-7 ngx_http_request_handler 方 法 的 执行 流程 


通常 来 说 ， 在 接收 完 HTTP 头 部 后 ， 是 无 法 在 一 次 Nginx 框 架 的 调度 中 处 理 完 一 个 请 求 
的 。 在 第 一 次 接收 完 HTTP 尖 部 后 ，HTTP 框 架 将 调度 ngx_http_process_request 方 法 开始 处 理 请 
求 ， 这 时 根据 图 11-6 中 的 流程 可 以 看 到 ， 如 果 某 个 checker 方 法 返回 了 NGX_OK， 则 将 会 把 控 
制 权 交还 给 Nginx 框 架 。 当 这 个 请 求 上 对 应 的 事件 再 次 触发 时 ，HTTP 框 架 将 不 会 再 调度 
ngx_http process request 方法 处 理 请 求 ， 而 是 由 ngx http_ request handler 方 法 开始 处 理 请 求 。 
下 面 来 看 看 图 11-7 中 列 出 的 ngx http_ request handler 方 法 的 流程 : 














1) ngx_http_ request handler 是 HTTP 请 求 上 读 / 写 事件 的 回调 方法 。 在 ngx_event t 结 构 体 表 
示 的 事件 中 ，data 成 员 指 向 了 这 个 事件 对 应 的 ngx_connection t 连 接 ， 而 根据 11.3 节 中 的 内 容 
可 以 看 到 ， 在 HTTP 框 架 的 ngx_connection t 结 构 体 中 的 data 成 员 则 指向 了 ngx_http_request t 结 
构 体 。 毫 无 疑问 ， 只 有 拥有 了 ngx_http_request t 结 构 体 才 可 以 处 理 HTTP 请 求 ， 而 第 一 个 步 又 
是 从 事件 中 取出 ngx http request t 结 构 体 。 








2) 检查 这 个 事件 的 write 可 写 标 志 ， 如 果 write 标 志 为 1， 则 调用 ngx http request t 结 构 体 
中 的 write_event handler 方 法 。 注 意 ， 我 们 在 ngx_http_handler 方 法 中 《〈 即 网 11-$ 的 第 6 步 ) 已 
经 将 write event handler 设 置 为 ngx http core run phases 方 法 ， 而 一 般 我 们 开发 的 不 太 复杂 的 
HTTP 模 块 是 不 会 重新 设置 write_ event handler 方 法 的 ， 因 此 ， 一 旦 有 可 写 事 件 时 ， 就 会 继续 
按照 图 11-6 的 流程 执行 ngx_http_core run phases 方 法 ， 并 继续 按 阶 段 调用 各 个 HTTP 模 块 实现 
的 方法 处 理 请 求 。 





3) 调用 ngx http request t 结 构 体 中 的 read event handler 方 法 。 注 意 比较 第 2 步 和 第 3 步 ， 
如 果 一 个 事件 的 读 写 标志 同时 为 1 时 ， 仅 write_event handler 方 法 会 被 调用 ， 即 可 写 事件 的 处 
理 优先 于 可 读 事件 〈 这 正 是 Nginx 高 性 能 设计 的 体现 ， 优 先 处 理 可 写 事 件 可 以 尽快 释放 内 
存 ， 尽 量 保持 各 HTTP 模 块 少 使 用 内 存 以 提高 并 发 能 力 ) 。 








4) 调用 ngx http run posted requests 方 法 执行 post 请 求 ， 参 见 11.7 节 。 
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以 上 重点 讨论 了 ngx http process request 和 nsgx http request handler 这 两 个 方法 ， 其 中 
ngx http process request 方法 负责 在 接收 完 ETTP 头 部 后 ， 第 一 次 与 各 个 HTTP 模 块 共同 按 阶段 
处 理 请 求 ， 而 对 于 ngx http request handler 方 法 ， 如 果 ngx http_process_request 没 能 处 理 完 请 
求 ， 这 个 请 求 上 的 事件 再 次 被 触 发 ， 那 束 将 由 此 方法 继续 处 理 了 。 





这 两 个 方法 的 共通 之 处 在 于 ， 它 们 都 会 先 按 阶段 调用 各 个 HTTP 模 块 处 理 请 求 ， 再 处 理 
post 请 求 。 关 于 post 请 求 的 内 容 下 文 会 介绍 ， 而 按 阶 段 处 理 请 求实 际 上 融 是 图 11-6 中 摘 述 的 流 
程 ， 也 就 是 通过 每 个 阶段 的 checker 方 法 来 实现 。 在 表 11-1 中 可 以 看 到 ， 在 各 个 HITP 模 块 能 
够 介入 的 7 个 阶段 中 ， 实 际 上 共享 了 4 个 checker 方 法 : ngx http_core generic phase、 





ngx http core rewrite phase、 ngx http core access phase、ngx http core content phase， 在 
10.6 节 中 我 们 曾经 简单 地 介绍 过 它们 。 


这 4 个 checker 方 法 的 主要 任务 在 于 ， 根 据 phase_ handler 执 行 某 个 HTTP 模块 实现 的 回调 方 
法 ， 并 根据 方法 的 返回 值 决定 : 当前 阶段 已 经 完全 结束 了 吗 ? 下 次 要 执行 的 回调 方法 是 哪 一 
个 ? 究竟 是 立刻 执行 下 一 个 回调 方法 还 是 先 把 控制 权 交 还 给 epoll? 下面 通过 介绍 这 4 个 
checker 方 法 来 回答 上 述 3 个 问题 〈 其 他 checker 方 法 仅 由 HTTP 框 架 使 用 ， 这 里 不 再 详细 介 


2 








11.6.1 ngx http core generic phase 


从 表 11-1 中 可 以 看 出 ， 有 3 个 HTTP 阶 段 都 使 用 了 ngx_http_core_generic_phase 作 为 它们 的 
checker 方 法 ， 这 意味 着 任何 试图 在 NGX_HTTP POST READ PHASE、 
NGX HTTP PREACCESS PHASE、NGX HTTP LOG PHASE 这 3 个 阶段 处 理 请 求 的 HTTP 模 
块 都 需要 了 解 ngx_http core generic phase 方 法 到 底 做 了 些 什么 。 图 11-8 中 描述 了 
ngx_http_core_generic_phase 方 法 的 流程 ， 可 以 看 到 ， 在 调用 了 当前 阶段 的 handler 方 法 后 ， 根 
据 返 回 值 的 不 同 可 能 导致 4 种 不 同 的 结 
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下 面 说 明 图 11-8 中 所 列 的 $ 个 步骤 。 


1) 首先 调用 HTTP 模 块 实现 的 handler 方 法 ， 这 个 方法 的 实现 当然 是 不 允许 有 阻塞 操作 
的 ， 它 会 立刻 返回 。 根 据 它 的 返回 值 类 型 ， 将 会 有 4 种 不 同 的 结果 : 返回 NGX_OK 时 直接 跳 
转 到 第 2 步 执行 ， 返 回 NGX DECLINED 时 跳 转 到 第 3 步 执 行 ， 返 回 NGX AGAIN 或 者 
NGX_DONE 时 跳 转 到 第 4 步 执 行 ， 返 回 其 他 值 时 跳 转 到 第 5 步 执 行 。 


2) 如 果 HTTP 模 块 实现 的 handler 方 法 返回 NGX OK， 这 意味 着 当前 阶段 已 经 执行 完毕 ， 
需要 跳 转 到 下 一 个 阶段 执行 。 例 如 ， 在 NGX _ HTTP ACCESS _ PHASE 阶段 中 可 能 有 两 个 
HTTP 模 块 都 注册 了 回调 方法 ， 在 执行 第 1 个 HTTP 模 块 的 回调 方法 时 ， 如 果 它 返回 了 
NGX_OK， 那 么 就 不 再 执行 第 2 个 HTTP 模 块 实现 的 回调 方法 了 ， 而 是 跳 转 到 下 一 个 阶段 (如 
NGX_HTTP_POST_ACCESS_PHASE) 开始 执行 。 注 意 ， 此 时 ngx_http_core_generic_phase 方 
法 会 返回 NGX _ AGAIN， 从 图 11-6 中 可 以 看 到 ， 非 NGX_OK 的 返回 值 不 会 使 HTTP 框 架 把 进程 
控制 权 交 还 给 epoll 等 事件 模块 ， 而 是 会 继续 立刻 执行 请 求 的 后 续 处 理 方法 。 
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1 ) 调 用 HTTP 模 块 实现 的 





handler 方 法 处 理 请 求 


[检查 handle 访 法 的 返回 值 ] 





2) 将 phase_handler 设 为 [返回 NGX_DECLINED] 


next 并 返回 NGX_AGAIN 





[返回 NGX_AGAIN 或 者 NGX_DONE] 


[返回 其 他 值 ] 3) phase_handler++ 





并 返回 NGX_AGAIN 


4) 和 直接 返回 NGX_OK) 


5 ) 调 用 ngx_ http_finalize _request 





结束 请 求 并 返回 NGX_OK 


图 11-8 ngx_http_core_generic_phase 方 法 的 执行 流程 


3) 如 果 handler 方 法 返回 NGX DECLINED， 则 会 执行 下 一 人 其 续 第 2 步 中 的 
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例子 ， 在 NGX_HTTP ACCESS _ PHASE 阶段 ， 第 1 个 HTTP 模 块 的 回调 方法 返回 
NGX_DECLINED 后 ， 下 一 个 将 要 执行 的 方法 仍然 属于 NGX_HTTP_ ACCESS_PHASE 阶 段 ， 
即 第 2 个 HTTP 模 块 实现 的 回调 方法 。 注 意 ， 这 时 ngx _ http core _generic phase 返回 的 仍然 是 
NGX _AGAIN， 它 意味 着 HTTP 框 架 会 紧 接 着 继续 执行 请 求 的 后 续 处 理 方法 。 


4) 如 果 handler 方 法 返回 NGX_AGAIN 或 者 NGX _ DONE， 则 意味 着 刚才 的 handler 方 法 无 
法 在 这 一 次 调度 中 处理 完 这 一 个 阶段 ， 它 需要 多 次 调度 才能 完成 ， 也 就 是 说 ， 刚 刚 执行 过 的 
handler 方 法 希望 :如果 请 求 对 应 的 事件 再 次 被 触发 时 ， 将 由 ngx_http_request_handler 通 过 
ngx_http_core_run_phases 再 次 调用 这 个 handler 方 法 。 直 接 返 回 NGX_OK 会 使 得 HTTP 框 架 立 刻 
把 控制 权 交 还 给 epoll 事 件 框架 ， 不 再 处 理 当 前 请 求 ， 唯 有 这 个 请 求 上 的 事件 再 次 被 触发 才 会 
继续 执行 。 
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1 ) 调用 HTTP 模 块 实现 的 
handler 处 理 方 法 


[检查 handle 方 法 的 返回 值 ] 





[返回 NGX_DECLINED] 


[返回 NGX_DONE] 2 ) phase_ handler+ 导 返 回 





NGX_AGAIN 


3 ) 直接 返回 
NGCX_OK 


4) 调用 ngx_http_finalize _request 


[返回 其 他 值 ] 





结束 请 求 并 返回 NGX_OK 


© 


图 11-9 ngx_http_core_rewrite_phase 方 法 的 执行 流程 
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5) 如 果 handler 方 法 返回 了 第 2、 第 3、 第 4 步 中 以 外 的 返回 值 ， 则 调用 
ngx http finalize request 结 束 请 求 。ngx http finalize request 方 法 中 的 参数 就 是 handler 方 法 的 返 


回 值 ， 其 影响 参见 11.10.6 节 。 





当 我 们 开发 的 HTTP 模 块 试图 介入 NGX _ HTTP POST READ PHASE、 
NGX HTTP PREACCESS PHASE、NGX HTTP_ LOG PHASE 这 3 个 阶段 处 理 请 求 时 ， 实 现 
的 handler 方 法 需要 根据 上 述 步 又 决定 返回 值 。ngx http_ core generic phase 可 以 帮助 我 们 较为 
简单 地 实现 强大 的 异步 无 阻塞 处 理 能 


11.6.2 ngx http core rewrite phase 


ngx_http_core_rewrite_phase 方 法 充当 了 用 于 重 写 URIL 的 
NGX _ HTTP SERVER REWRITE PHASE 和 NGX HTTP REWRITE PHASE 这 两 个 阶段 的 
checker 方 法 。 图 11-9 中 描述 了 ngx http core rewrite phase 方法 的 流程 ， 可 以 看 到 ， 在 调用 了 
当前 阶段 的 handler 方 法 后 ， 根 据 返 回 值 的 不 同 可 能 会 导致 3 种 结 


下 面 简要 描述 一 下 图 11-9 中 所 列 的 4 个 步骤 。 


1) 首先 调用 HTTP 模块 实现 的 handler 方 法 ， 根 据 它 的 返回 值 类 型 ， 将 会 有 3 种 不 同 的 结 
果 : 返回 NGX_ DECLINED 时 跳 转 到 第 2 步 执 行 ， 返回 NGX_DONE 时 跳 转 到 第 3 步 执行 ， 返 回 
其 他 值 时 跳 转 到 第 4 步 执行 。 





2) 如 果 handler 方 法 返回 NGX DECLINED， 将 phase handler 加 1 表示 将 要 执行 下 一 个 回调 
方法 。 注 意 ， 此 时 返回 的 是 NGX_AGAIN，HTTP 框 架 不 会 把 进程 控制 权 交 还 给 epoll 事 件 框 
架 ， 而 是 继续 立刻 执行 请 求 的 下 一 个 回调 方法 。 


3) 如 果 handler 方 法 返回 NGX_ DONE， 则 意味 着 刚才 的 handler 方 法 无 法 在 这 一 次 调度 中 
处 理 完 这 一 个 阶段 ， 它 需要 多 次 的 调度 才能 完成 。 注 意 ， 此 时 返回 NGX_OK， 它 会 使 得 
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HITP 框 以 立刻 把 控制 权 交 还 给 epoll 等 事件 模块 ， 不 再 处 理 当 前 请 求 ， 唯 有 这 个 请 求 上 的 事 
件 再 次 被 触及 时 才 会 继续 执行 。 


4) 如 果 handler 方 法 返回 除去 NGX DECLINED 或 者 NGX DONE 以 外 的 其 他 值 ， 则 调用 
ngx_http_finalize_request 结 束 请 求 ， 其 参数 为 handler 方 法 的 返回 值 。 


可 以 注意 到 ，ngx_http_core_rewrite_phase 方 法 与 ngx_http_core_generic_phase 方 法 有 一 个 
显著 的 不 同 点 : 前 者 永远 不 会 导致 跨 过 同一 个 HITP 阶 段 的 其 他 处 理 方法 ， 就 直接 跳 到 下 一 
个 阶段 来 处 理 请 求 。 原 因 其 实 很 简单 ， 可 能 有 许多 HTTP 模 块 在 
NGX HTTP SERVER REWRITE PHASE 和 NGX HTTP _ REWRITE PHASE 阶 段 同 时 处 理 重 写 
URL 这 样 的 业务 ，HTTP 框 架 认 为 这 两 个 阶段 的 HTTP 模 块 是 完全 平等 的 ， 序 号 靠 前 的 HTTP 
模块 优先 级 并 不 会 更 高 ， 它 不 能 决定 序号 靠 后 的 HTTP 模 块 是 否 可 以 再 次 重 写 URL。 因 此 ， 
ngx_http_core rewrite phase 方法 绝对 不 会 把 phase handler 直 接 设置 到 下 一 个 阶段 处 理 方法 的 
流程 中 ， 即 不 可 能 存在 类 似 下 面 的 代码 。 





ngx _ int t ngx http core rewrite phase (ngxX http request t r, ngx http phase handler t ph) 











r->phase handler = ph->next; 





11.6.3 ngx http core access phase 


ngx_http_core_access_phase 方 法 是 仅 用 于 NGX_HTTP_ACCESS_PHASE 阶 段 的 处 理 方 
法 ， 这 一 阶段 用 于 控制 用 户 发 起 的 请 求 是 否 合法 ， 如 检测 客户 端的 人 P 地 址 是 否 允 许 访问 。 它 
涉及 nginx.conf 配 置 文件 中 satisfy 配 置 项 的 参数 值 ， 见 表 11-2。 


表 11-2 ”相对 于 NGX_HTTP ACCESS_PHASE 阶 段 处 理 方 法 ，satisfy 配 置 项 参数 的 意义 
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satisfy 的 参数 


all 


any 


NGX _HITP ACCESS_PHASE 阶段 可 能 有 很 多 HITP 模块 都 对 控制 请 求 的 访问 权限 感 兴趣 ， 


那么 以 哪 一 个 为 准 呢 ? 当 satisfy 的 参数 为 al 时， 这 些 HTTP 模块 必须 同时 发 生 作 用 ， 即 以 该 阶 
段 中 全 部 的 handler 方法 共同 决定 请 求 的 访问 权限 ， 换 名 话说 ， 这 一 阶段 的 所 有 handler 方法 必须 
全 部 返回 NGX_OK 才能 认为 请 求 具有 访问 权限 

与 all 相反 ， 为 any 时 意味 着 在 NGX_HTTP ACCESS PHASE 阶段 只 要 有 任意 一 个 HITP 
异 块 认为 请 求 合 法 ， 就 不 用 再 调用 其 他 HTTP nt :检查 了 ， 可 以 认为 请 求 是 具有 访问 权限 
的 。 实 际 上 ， 的 情况 有 些 复 杂 : 如 果 其 中 任何 一 个 handler 方法 返回 NGX_OK， 则 认为 请 求 
具有 访问 权限 ; 如 果 某 一 个 handler 方法 返回 403 或 者 401， FE 认为 请 求 没有 访问 权限 ， 还 需要 
丛 查 NGX_HTTP_ACCESS_PHASE 阶段 的 其 他 handler 方法 。 也 就 是 说 ，any 配置 项 下 任何 一 个 
handler 方法 一 旦 认为 请 求 具有 访问 权限 ， 就 认 es 继续 向 下 执行 ; 如 果 其 中 一 
个 handler 方法 认为 没有 访问 权限 ， 则 未 必 以 此 为 准 ， 还 需要 检测 其 他 的 hanlder 方法 。all 和 any 
有 点 像 “&&” 和 “||” 的 关系 


对 于 表 11-2 的 any 配 置 项 ， 是 通过 ngx http request t 结 构 体 中 的 access_code 成 员 来 传递 
handler 方 法 的 返回 值 的 ， 因 此 ，ngx http core _ access _phase 方 法 会 比较 复杂 ， 如 图 11-10 所 


小 。 
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[检查 请 求 的 main 指 针 是 和 否 指 回 自己] 


C2 


[当前 请 求 就 是 原始 请 求 ] 


[当前 请 求 不 是 原始 请 求 ] 


1 ) 将 phase_handler 设 为 next 


2) 调 用 HTTP 模 块 实现 的 并 返回 NGX_AGAIN 





















handler 处 理 方法 
[检查 handler 方 法 的 返回 值 ] 


[返回 NGX_AGAIN 或 者 NGX_DONE] 


<> 


[返回 其 他 值 ] 












[返回 NGX_DECLINED 1] 
3) 直接 返回 
5) 取 出 当前 请 求 匹 配 的 NGX_OK 
location 配 团 块 
[ 先 检 查 location 下 satisfy 配置 项 的 值 , 再 检查 handler 方 法 的 返回 值 ] 


[satisfy 配置 为 al] 
4) phase_handler ++ 


[satisfy 配 置 为 any] 半 过 加 NO AGAIN 






[返回 NGX_OK] 


[返回 NGX_HTTP_FORBIDDEN 或 者 CS 
NGX_HTTP_UNAUTHORIZED] 


6) 将 access_code 设 置 为 





handler 返 回 值 
[返回 非 NGX_OK 值 ] 


7) 将 access_code 


设置 为 0 





8) 调用 ngx_http_finalize_request 
结束 请 求 并 返回 NGX_OK 


图 11-10 ”ngx_http_core_access_phase 方 法 的 执行 流程 
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下 面 开 始 分 析 ngx_http core access_ phase 方法 的 流程 。 





1) 既然 NGX_HTTP ACCESS _ PHASE 阶段 用 于 控制 客户 端 是 否 有 权限 访问 服务 ， 那 么 
它 就 不 需要 对 子 请 求 起 作用 。 如 何 判断 请 求 完 竟 是 来 自 客户 端 的 原始 请 求 还 是 被 派生 出 的 子 
请 求 呢 ? 很 简单 ， 检 查 ngx_http request tt 结构 体 中 的 main 指 针 即 可 。 在 11.3 市 介绍 过 的 
ngx_http_init_request 方 法 会 把 main 指 针 指 同 其 自 丑 ， 而 由 这 个 请 求 派生 出 的 其 他 子 请 求 中 的 
main 指 针 ， 仍 然 会 指向 ngx_http_init_request 方 法 初始 化 的 原始 请 求 。 因 此 ， 检 查 main 成 员 与 
ngx_http_request t 自 身 的 指针 是 否 相 等 即 可 ， 如 下 面 的 源 代码 。 




















if (r != r->main) { 
r->phase handler = ph->next; 
return NGX AGAIN; 
} 











如 果 当 前 请 求 只 是 一 个 派生 出 的 子 请 求 的 话 ， 是 不 需要 执行 
NGX _HTTP ACCESS PHASE 阶段 的 处 理 方法 的 ， 那 么 直接 将 phase_ handler 设 为 下 一 个 阶段 
(实际 上 是 NGX HTTP POST ACCESS _ PHASE 阶段 ) 的 处 理 方法 的 序号 。 这 时 会 返回 
NGX AGAIN， 也 就 是 希望 HTTP 框 架 立 刻 执 行 新 的 HTTP 阶段 的 处 理 方法 。 








2) 如 果 当 前 请 求 就 是 来 自 客户 端的 原始 请 求 ， 那 么 调用 HTTP 模 块 在 这 一 阶段 中 实现 
handler 方 法 ， 它 的 返回 值 将 会 导致 出 现 3 个 分 文 : 返回 NGX_ AGAIN 或 者 NGX_DONE 时 跳 转 
到 第 3 步 执 行 ; 返回 NGX DECLINED 时 跳 转 到 第 4 步 执行 ， 返回 其 他 值 时 跳 转 到 第 5 步 继 续 癌 
下 执行 。 同 时 ， 在 第 $ 步 之 后 ， 这 个 返回 值 由 于 nginx.conf 文 件 中 配置 项 satisfy 的 参数 值 不 同 ， 
也 将 具有 不 同 的 意义 。 





3) 返回 NGX AGAIN 或 者 NGX_ DONE 意 味 着 当前 的 NGX_HTTP ACCESS PHASE 阶段 
没有 一 次 性 执行 完毕 ， 所 以 在 这 一 步 中 会 暂时 结束 当前 请 求 的 处 理 ， 将 控制 权 交还 给 事件 模 
块 ，ngx http core access_phase 方 法 结束 。 当 请 求 中 对 应 的 事件 再 次 触发 时 才 会 继续 处 理 访 
请 求 。 











NNn httpo://ww linuxorobe. con 








4) 返回 NGX_ DECLINED 意 味 着 handler 方 法 执行 完毕 且 “ 意 犹 未 尽 "”， 和 希望 立刻 执行 下 一 
个 handler 方 法 ， 无 论 其 是 否 属于 NGX HTTP ACCESS _ PHASE 阶段 ， 在 这 一 步 中 只 需要 把 


phase_ handler 加 1， 同 时 ngx http core _ access phase 方 法 返回 NGX AGAIN 即 可 。 





5) 现在 开始 处 理 非 第 3、 第 4 步 中 返回 值 的 情况 。 由 于 NGX_HTITP_ ACCESS_PHASE 阶 
段 是 在 NGX_HTTP_FIND_CONFIG PHASE 阶段 之 后 的 ， 因 此 这 时 请 求 已 经 找到 了 匹配 的 
location 配 置 块 ， 先 把 location 块 对 应 的 ngx http core loc conf t 配 置 结构 体 取出 来 ， 因 为 这 里 
有 一 个 配置 项 satisfy 是 下 一 步 需 要 用 到 的 。 


6) 检查 ngx_http_core_loc_conf t 结 构 体 中 的 satis 人 成 员 ， 如 果 值 为 
NGX _HTTP_SAIISFY_ ALL《〈 即 nginx.conf 文 件 中 配置 了 satisfy all 参 数 ) ， 则 意味 着 所 有 
NGX _ HTTP ACCESS _ PHASE 阶段 的 handler 方 法 必须 共同 作用 于 这 个 请 求 。 这 时 ，handler 方 
法 的 返回 值 就 具有 不 同 的 意义 了 。 如 果 它 的 返回 值 是 NGX_OK， 则 意味 着 这 个 handler 方 法 所 
在 的 HTTP 模块 认为 当前 请 求 是 具备 访问 权限 的 ， 需 要 再 次 检查 
NGX _ HTTP ACCESS _ PHASE 阶段 的 下 一 个 HTTP 模 块 的 handler 方 法 ， 于 是 会 跳 到 第 4 步 执 
行 ， 反 之， 如 果 返 回 值 不 是 NGX OK， 就 意味 着 当前 请 求 无 权 访问 服务 ， 这 时 需要 跳 到 第 8 
步调 用 ngx_http_finalize request 方法 结束 请 求 ， 方 法 的 参数 也 就 是 这 个 返回 值 。 




















如 果 ngx http core loc_conf t 结 构 体 中 的 satisfy 成 员 值 为 NGX HTTP SATISFY ANY ( 即 
nginx.conf 文 件 中 配置 了 satisfy any 参 数 ) ， 也 就 是 说 ， 并 不 强制 要 求 
NGX HTTP ACCESS PHASE 阶 段 的 所 有 handler 方 法 必须 同时 起 作用 ， 那 么 这 时 handler 方 法 
的 返回 值 又 具有 了 不 同 的 意义 。 如 果 该 返回 值 是 NGX_OK， 则 表示 第 2 步 执行 的 handler 方 法 
认为 这 个 请 求 有 权限 访问 服务 ， 而 且 不 用 再 调用 NGX_HTTP_ACCESS_PHASE 阶 段 的 其 他 
handler 方 法 了 ， 直 接 跳 到 第 7 步 执行 ， 如 果 返 回 值 是 NGX_HTTP_ FORBIDDEN 或 者 
NGX HTTP UNAUTHORIZED， 则 表示 这 个 HTTP 模块 的 handler 方 法 认为 请 求 没有 权限 访问 
服务 ， 但 只 要 NGX_HTTP ACCESS _ PHASE 阶段 的 任何 一 个 handler 方 法 返回 NGX_OK 就 认为 
请 求 合 法 ， 所 以 后 续 的 handler 方 法 可 能 会 更 改 这 一 结果 。 这 时 将 请 求 的 access_code 成 员 设置 
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为 handler 方 法 的 返回 值 ， 用 于 传递 当前 HTTP 模 块 的 处 理 结果 ， 然 后 跳 到 第 4 步 执行 下 一 个 
handler 方 法 ， 如 果 返 回 值 为 其 他 值 ， 可 以 认为 请 求 绝对 无 权 访问 服务 ， 则 跳 到 第 8 步 执行 。 


7) 上 面 已 经 解释 过 ， 在 satisfy any 配 置 下 ，handler 方 法 返回 NGX OK 时 意味 着 这 个 请 求 
具备 访问 权限 ， 将 请 求 的 access_code 成 员 置 为 0， 跳 到 第 1 步 执行 。 


8) 调用 ngx http finalize request 方法 结束 请 求 。 


虽然 ngx_http_core_access_phase 方 法 有 些 复杂 ， 即 它 为 NGX_HTTP_ACCESS_PHASE 阶 
段 中 的 handler 方 法 的 返回 值 增加 了 过 多 的 含义 ， 但 当 我 们 开发 的 HTTP 模 块 需 要 处 理 请 求 的 
访问 权限 时 ， 就 会 发 现 ngx_http core access_phase 方 法 给 我 们 带 来 强大 的 功能 ， 可 以 实现 复 
杂 的 权限 控制 。 


11.6.4 ngx http core content phase 


ngx http core content phase 是 NGX HTTP CONTENT PHASE 阶 段 的 checker 方 法 ， 可 以 
说 它 是 我 们 开发 HTTP 模 块 时 最 常用 的 一 个 阶段 了 。 顾 名 思 义 ， 
NGX_HTTP_CONTENT PHASE 阶 段 用 于 真正 处 理 请 求 的 内 容 。 其 余 10 个 阶段 中 各 HTTP 模 块 
的 处 理 方法 都 是 放 在 全 局 的 ngx_http_core_main conf t 结 构 体 中 的 ， 也 就 是 说 ， 它 们 对 任何 一 
个 HTTP 请 求 都 是 有 效 的 。 但 在 NGX _HTTP CONTENT _ PHASE 阶段 却 很 自然 地 有 另 一 种 需 
求 ， 有 的 HTTP 模块 可 能 仅 希望 在 这 个 处 理 请 求 内 容 的 阶段 ， 仅 仅 针对 某 种 请 求 唯一 生效 ， 
而 不 是 对 所 有 请 求生 效 。 例 如 ， 仅 当 请求 的 URI 匹 配 了 配置 文件 中 的 某 个 location 块 时 ， 再 根 
据 location 块 下 的 配置 选择 一 个 HITP 模 块 执行 它 的 handler 处 理 方法 ， 并 以 此 蔡 代 
NGX HTTP CONTENT PHASE 阶 段 的 其 他 handler 方 法 (这 些 handler 方 法 对 于 该 请 求 将 得 不 
到 执行 ) 。 





既然 我 们 希望 请 求 在 NGX _ HTTP CONTENT _ PHASE 阶段 的 handler 方 法 仅 与 1ocation 相 
关 ， 那 么 就 肯定 与 ngx http core loc_conf t 结 构 体 相关 了 ， 注 意 handler 成 员 : 
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struct ngx http core loc conf s { 


ngx http handler pt handler; 





这 个 handler 成 员 属 于 nginx.conf 中 匹配 了 请 求 的 location 块 下 配置 的 HTTP 模 块 (当然 ， 如 
果 请 求 匹配 的 location 块 下 没有 配置 HITP 模 块 处 理 请 求 ， 那 么 这 个 handler 指 针 将 为 NULL 空 指 
针 ) 。 回 顾 一 下 第 3 章 中 的 ngx_http_mytest 方 法 ， 它 正 是 在 某 个 location 下 检测 到 mytest 配 置 项 
后 ， 取 到 当前 location 下 的 ngx http core loc conf t 结 构 体 ， 并 把 handler 成 员 设置 为 希望 在 
NGX HTTP_CONTENT PHASE 阶 段 处 理 请 求 的 ngx http mytest handler 方 法 的 。 


实际 上 ， 为 了 加 快 处 理 速 度 ，HTTP 框 架 叉 在 ngx http request t 结 构 体 中 增加 了 一 个 成 员 
content handler (参见 11.3.1 节 ) ， 在 NGX HTTP FIND CONFIG PHASE 阶 段 就 会 把 它 设 为 
匹配 了 请 求 URI 的 location 块 中 对 应 的 ngx http_core loc _conf t 结 构 体 的 handler 成 员 (参见 
Nginx 源 代码 的 ngx http update _ location config 方 法 ) 。 


以 上 所 述 是 NGX _ HTTP CONTENT _ PHASE 阶段 的 特殊 之 处 ， 当 然 ， 它 还 可 以 像 其 余 10 
个 阶段 一 样 具 备 全 局 生效 的 handler 方 法 ， 但 如 果 设 置 了 content handler 方 法 ， 会 优先 以 
content handler 为 准 ， 如 图 11-11 所 示 。 


下 面 详细 介绍 一 下 ngx http core content phase 方 法 是 如 何人 处 理 
NGX HTTP_CONTENT PHASE 阶 段 的 请 求 的 。 


1) 首先 检测 ngx http request t 结 构 体 的 content handler 成 员 是 否 为 空 ， 其 实 就 是 看 在 
NGX _ HTTP FIND_ CONFIG PHASE 阶段 匹配 了 URI 请 求 的 location 内 ， 是 否 有 HTTP 模 块 把 处 
理 方法 设置 到 了 nsgx http_core loc_conf t 结 构 体 的 handler 成 员 中 。 如 果 content handler 为 空 ， 


则 跳 到 第 2 步 开 始 执 行 全 局 有 效 的 handler 方 法 ; 否则 仅 执行 content handler 方 法 ， 看 看 源 代 码 
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中 做 了 些 什么 ， 如 下 所 示 。 





r->write event handler = ngx http request empty handler; 
ngx http finalize request(r, r->content handler (r)); 





其 中 ， 首 先 设置 ngx_http_request t 结 构 体 的 write_event_handler 成 员 为 不 做 任何 事 的 
ngx_http_request_empty_handler 方 法 ， 也 就 是 告诉 HTTP 框架 再 有 可 写 事 件 时 就 调用 
ngx_http_request_empty_handler 直 接 把 控制 权 交 还 给 事件 模块 。 为 何 要 这 样 做 呢 ? 因为 HTTP 
框架 在 这 一 阶段 调用 HTTP 模 块 处 理 请 求 就 意味 着 接 下 来 只 希望 该 模块 处 理 请 求 ， 先 把 
write event handler 强 制 转化 为 ngx http request _ empty handler， 可 以 防止 该 HTTP 模 块 异步 地 
处 理 请 求 时 却 有 其 他 HTTP 模 块 还 在 同时 处 理 可 写 事件 、 向 客户 端 发 送 响 应 。 接 下 来 调用 
content_handler 方 法 处 理 请 求 ， 并 把 它 的 返回 值 作为 参数 传递 给 ngx_http_ finalize_request 方 法 
来 结束 请 求 。ngx_http_finalize_request 方 法 是 非常 复杂 的 ， 它 会 根据 引用 计数 来 确定 自己 的 行 
为 ， 有 具体 参见 11.10.6 节 。 
































2) 在 没有 content handler 方 法 时 ， 又 回 到 了 我 们 惯用 的 方式 ， 首 先 根据 phase_ handler 序 
号 调用 handler 处 理 方法 ， 检 测 它 的 返回 值 : 当 返 回 值 为 NGX_ DECLINED 时 跳 到 第 4 步 ， 否 则 
跳 到 第 3 步 执 行 


3) 如 果 NGX_HTTP_CONTENT PHASE 阶 段 中 全 局 的 handler 方 法 没有 返回 
NGX DECLINED， 则 意味 着 不 再 执行 该 阶段 的 其 他 handler 方 法 。 因 此 ， 这 时 简单 地 以 
handler 方 法 作为 参数 调用 ngx http finalize request 结束 请 求 即 可 。 同 时 ， 
ngx http core content phase 方 法 返回 NGX OK， 表示 归还 控制 权 给 事件 模块 。 
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「 检 查 匹 配 了 请 求 网 了 content_handle 芒 法 | 


‘> 


[不 存在 content_hand le 方法 | 


[存在 content_handler 方 法 | 


1 ) 调用 content handler 


方法 并 结束 请 求 





2) 调用 HTTP 模 块 实现 的 


handler 处 理 方 法 
[检查 handle 访 法 的 返回 值 ] 





[返回 值 不 是 NGX_DECLINED] 
[返回 NGX_DECLINED] 3 ) 调用 ngx_http_finalize _request 


结束 请 求 





4 ) 转 到 下 一 个 





ngx_http_phase_handler_t 处 理 方法 
[检查 ngx_http_phase_handlert 的 checker 是 否 实现 ] 


Cs [checker 方 法 存在 ] 


[checker 方 法 不 存在 ,检查 请 求 的 URI] 5) phase_handler++ 并 返回 


NGX_AGAIN 





[请 求 的 URI 以 /结尾 ] 








6) 调用 ngx_http_finalize_request 
结束 请 求 ， 返 回 403 


7) 调用 ngx_http_finalize _request 


结束 请 求 ， 返 回 404 


图 11-11 negx_http_core_content_phase 方 法 的 流程 


4) 虽然 handler 方 法 返回 了 NGX DECLINED， 表 示 希 望 执 行 本 阶段 的 下 一 个 handler 方 
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法 ， 但 是 当前 的 handler 方 法 是 否 已 经 是 最 后 一 个 handler 方 法 了 呢 ? 这 需要 进行 检测 ， 首 先 转 
到 数组 中 的 下 一 个 handler 方 法 ， 检 测 其 checker 方 法 是 否 存在 ， 若 存在 ， 则 跳 到 第 5$ 步 执行 ， 
右 不 存在 ， 则 结束 请 求 ， 但 需要 根据 URI 确 定 返 回 什 么 样 的 HITP 啊 应 ， 如 果 URI 是 以 “/” 结 
尾 ， 则 跳 到 第 6 步 执 行 ， 否 则 路 到 第 7 步 执 行 。 





5) 既然 handler 方 法 返回 NGX_ DECLINED 和 希望 执行 下 一 个 handler 方 法 ， 那 么 这 一 步 把 请 
求 的 phase handler 序 号 加 1，ngx http core content phase 方 法 返回 NGX _ AGAIN， 表示 希望 
HTTP 框 架 立 刻 执 行 下 一 个 handler 方 法 。 


6) 以 NGX_HTITP_ FORBIDDEN 作 为 参数 调用 ngx_http_finalize_ request 方法 ， 表 示 结 束 请 





求 并 返回 403 错 误 码 。 同 时 ，ngx http core content phase 方 法 返回 NGX _ OK， 表示 交还 控制 权 
给 事件 模块 。 


7) 以 NGX_HTTP_NOT_FOUND 作 为 参数 调用 ngx_http_finalize_ request 方 法 ， 表 示 结 束 请 





求 并 返回 404 错 误 码 。 同 时 ，ngx http core content phase 方 法 返回 NGX OK， 表 示 交 还 控制 权 
给 事件 模块 。 


NGX_HTTP_CONTENT_PHASE 阶 段 是 各 HTTP 模 块 最 常 介 入 的 阶段 。 只 有 对 


ngx_http_core_content_ phase 方法 的 流程 足够 熟悉 ， 才 能 实现 复杂 的 功能 。 


er 注意 从 ngx_http_core_content_phase 方 法 中 可 以 看 到 ， 请 求 在 第 10 个 阶段 
NGX_HTTP_CONTENT_PHASE 后 ， 并 没有 去 调用 第 11 个 阶段 NGX_HTTP_LOG_PHASE 的 
处 理 方法 ， 通 过 比较 11.6 节 的 其 他 checket 方 法 ， 就 会 发 现 它 与 之 前 的 方法 都 不 同 。 事 实 上 ， 
记录 访问 日 志 是 必须 在 请 求 将 要 结束 时 才能 进行 的 ， 因 此 ，NGX_HTTP_ LOG_PHASE 阶 段 


的 回调 方法 在 11.10.2 节 介绍 的 ngx_http_free_request 方 法 中 才 会 调用 到 。 
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11.7 subrequest 与 post 请 求 


从 11.6 节 中 可 以 看 到 ，HTTP 框 架 无 论 是 调用 ngx_ http process request 方法 〈 首 次 从 业务 
上 处 理 请 求 〉》 还 是 ngx_http_request_handler 方 法 《TCP 连接 上 后 续 的 事件 触发 时 〉 处 理 请 求 ， 
最 后 都 有 一 个 步骤 ， 就 是 调用 ngx http run posted requests 方 法 处 理 post 请 求 〈 如 图 11-$ 中 的 
第 8 步 、 图 11-7 中 的 第 4 步 ) 。 那 么 ， 什 么 是 post 请 求 ? 为 什么 要 定义 post 请 求 ? post 请 求 又 是 


怎样 实现 于 HTTP 框 架 中 的 呢 ? 本 节 内 容 将 回答 这 3 个 问题 。 








Nginx 使 用 的 完全 无 阻塞 的 事件 张 动 框架 是 难以 编写 功能 复杂 的 模块 的 ， 可 以 想见 ， 一 
个 请 求 在 处 理 一 个 TCP 连 接 时 ， 将 需要 处 理 这 个 连接 上 的 可 读 、 可 写 以 及 定时 器 事件 ， 而 可 
读 事 件 中 义 包含 连接 建立 成 功 、 连 接 关 闭 事件 ， 正 第 的 可 读 事 件 在 接收 到 HTTP 的 不 同 部 分 
时 又 要 做 不 同 的 处 理 ， 这 束 比 较 复杂 了。 如果 一 个 请 求 同 时 需要 与 多 个 上 游 服 务 器 打交道 ， 
同时 处 理 多 个 TCP 连 接 ， 那 么 它 需 要 处 理 的 事件 束 太 多 了 ， 这 种 复杂 撤 会 使 得 模块 难以 维 
护 。Nginx 解 决 这 个 问题 的 手段 就 是 第 5 革 中 介绍 过 的 subreques 卉 L 制 。 














subrequest 机 制 有 以 下 两 个 特点 : 


: 从 业务 上 把 一 个 复杂 的 请 求 拆 分 成 多 个 子 请 求 ， 由 这 些 子 请 求 共同 合作 完成 实际 的 用 
户 请 求 。 


每 一 个 HTTP 模 块 通常 只 需要 关心 一 个 请 求 ， 而 不 用 试图 掌握 派生 出 的 所 有 子 请 求 ， 
这 极 大 地 降低 了 模块 的 开发 复杂 度 。 





这 两 个 特点 使 得 用 户 可 以 通过 开 友 多 个 功能 相对 单一 独立 的 模块 ， 来 共同 完成 复杂 的 业 
务 。 


post 请 求 的 设计 就 是 用 于 实现 subrequest 子 请 求 机 制 的 ， 如 果 一 个 请 求 具备 了 post 请 求 ， 
并 且 HTTP 框 架 保 证 post 请 求 可 以 在 当前 请 求 执行 完毕 后 获得 执行 机 会 ， 那 么 subrequest 功 能 
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就 可 以 实现 了 。 子 请 求 的 设计 在 数据 结构 上 是 通过 ngx_http_request tt 结构 体 的 3 个 成 员 
(posted_requests、parent、main〉 来 保证 的 。 下 面 看 一 下 表示 单 癌 链表 的 posted_requests 成 
员 ， 它 的 类 型 是 ngx http posted_request t 结 构 体 ， 如 下 所 示 。 








typedef struct ngx http posted request s ngx http posted request t; 
struct ngx http posted request s { 
// 指向 当前 待 处 理子 请 求 的 





ngx http request 七 结构 体 


ngx http request 七 *request; 
// 指向 下 一 个 子 请 求 ， 如 果 没有 ， 则 为 


NULL 空 指针 


ngx http posted request 七 *next; 
}; 





这 样 ， 通 过 posted_requests 束 把 各 个 子 请 求 以 捍 回 链表 的 数据 结构 形式 组 织 起 来 了 。 


ngx_http_request_t 结 构 体 中 的 parent 指 同 了 当前 子 请 求 的 父 请 求 ， 这 为 子 请 求 铝 前 寻找 父 
请 求 提供 了 可 能 性 。 


ngx_http_request_ {t 结 构 体 中 的 main 成 员 始 终 指 同一 系列 有 杀 缘 关系 的 请 求 中 的 唯一 的 那 
个 原始 请 求 。 我 们 可 以 在 任何 一 个 子 请 求 中 通过 main 成 员 找到 原始 请 求 ， 而 无 论 怎 样 执行 子 
请 求 ， 都 是 围绕 着 main 指 向 的 原始 请 求 进行 的 ， 在 图 11-12 中 可 以 看 到 。 
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[检查 Ngin a | 


X 


‘> 


[与 客户 端的 TCP 连 接 存 在 ] 


[TCP 连 接 已 销毁 ] 


图 攻取 厚 始 请 求 postt “|_requ "sts 





和 证 表 的 首 个 post 请 求 
| 检查 post 请 求 是 否 存 在 | 


中 


| 具 哈 post 请 求 | 


| post 请 求 不 存 在 | 


2) 将 原始 请 求 的 posted_requests 
成 员 指向 链表 中 的 下 一 个 post 请 求 


3 ) 执 行当 前 post 请 求 的 
write _event_handler 方 法 





图 11-12 post 请 求 的 执行 


ngx_http_request_t 结 构 体 中 的 count 成 员 将 作为 引用 计数 ， 每 当 铂 生出 子 请 求 时 ， 原 始 请 
求 的 count 成 员 都 会 加 1， 在 真正 销毁 请 求 前 ， 可 以 通过 检查 count 成 员 是 否 为 0 以 确认 是 售 销 
驶 原始 请 求 ， 这 样 可 以 做 到 唯 有 所 有 的 子 请 求 都 结束 时 ， 原 始 请 求 才 会 销毁 ， 斥 存 池 、TCP 
连接 等 资源 才 会 释放 。 


对 于 subrequest 子 请 求 的 用 法 ， 可 参见 5.4 方 ， 这 里 不 再 资 述 。 图 11-12 展 示 
ngx_http_run_posted_requests 方 法 是 怎么 执行 一 个 请 求 的 post 请 求 的 ， 也 就 是 如 果 一 个 请 求 拥 
有 子 请 求 时 ， 子 请 求 是 怎么 被 调度 的 。 
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从 图 11-12 中 可 以 看 到 ， 在 执行 荣 一 个 请 求 时 ， 它 的 所 有 post 请 求 都 可 能 被 执行 一 过 。 下 
面 详细 介绍 以 上 流程 。 


1) 首先 检查 连接 是 否 已 销毁 ， 如 果 连 接 被 销毁 ， 就 结束 ngx_http_run_posted_requests 方 
法 ， 否 则 根据 ngx_http_request_t 结 构 体 中 的 main 成 员 找到 原始 请 求 ， 这 个 原始 请 求 的 
posted requests 成 员 指 同 待 处 理 的 post 请 求 组 成 的 单 链 表 ， 如 果 posted_ requests 指 向 NULL 空 指 
针 ， 则 结束 ngx_http_run posted_ requests 方 法 ， 否 则 取出 链表 中 首 个 指向 post 请 求 的 指针 ， 并 
跳 到 第 2 步 执 行 。 


2) 将 原始 请 求 的 posted_requests 指 针 指 癌 链表 中 下 一 个 post 请 求 ( 通 过 第 1 个 post 请 求 的 
next 指 针 可 以 获得 ) ， 当 然 ， 下 一 个 post 请 求 有 可 能 不 存在 ， 这 在 下 一 次 循环 中 就 会 检测 
到 | O 

3) 调用 这 个 post 请 求 ngx_http_ request t 结 构 体 中 的 write_event handler 方 法 。 为 什么 不 是 


执行 read_event_handler 方 法 呢 ? 原 因 很 简单 ， 子 请 求 不 是 被 网 络 事件 驱动 的 ， 因 此 ， 执 行 
post 请 求 时 就 相当 于 有 可 写 事件 ， 由 Nginx 主 动 做 出 动作 。 











在 本 市 可 以 看 到 ，HTTP 框 架 在 处 理 一 个 请 求 时 ， 如 果 发 现 其 有 子 请 求 则 一 定 会 处 理 。 
通过 修改 原始 请 求 的 posted requesfts 指 针 ， 甚 至 还 可 以 控制 从 哪 一 个 子 请 求 开 始 执行 ， 当 
然 ， 直 接 修改 HTTP 框架 中 的 成 员 很 容易 出 错 ， 一 定 要 慎重 。 
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11.8 ”处 理 HTTP 包 体 





本 节 开 始 介 绍 HTTP 框 架 为 HTTP 模 块 提 供 的 工具 方法 。 在 HTTP 中 ， 一 个 请 求 通常 由 必 
选 的 HTTP 请 求 行 、 请 求 头 部 ， 以 及 可 选 的 包 体 组 成 ， 因 此 ， 在 接收 完 HTTP 头 部 后 ， 就 可 以 
开始 调用 各 HTTP 模 块 处 理 请 求 了 了 ( 见 11.6 节 ) ， 然 后 由 HTTP 模 块 决定 如 何 处 理 包 体 。 





HTTP 框 架 提 供 了 两 种 方式 处 理 HITP 包 体 ， 当 然 ， 这 两 种 方式 保持 了 完全 无 阻塞 的 事件 
驱动 机 制 ， 非 和 营 高 效 。 第 一 种 方式 就 是 把 请 求 中 的 包 体 接 收 到 内 存 或 者 文件 中 ， 当 然 ， 由 于 
包 体 的 长 度 是 可 变 的 ， 同 时 内 存 义 是 有 限 的 ， 因 此 ， 一 般 都 是 将 包 体 存放 到 文件 中 (本 市 不 
会 详细 讨论 包 体 的 存储 集 略 》》。 第 二 种 方式 是 选择 丢弃 包 体 ， 注 意 ， 丢 茎 不 等 于 可 以 不 接收 
包 体 ， 这 样 做 可 能 会 叶 致 客户 端 出 现 发 送 请 求 超时 的 错误 ， 所 以 ， 这 个 丢弃 只 是 对 于 HTTP 
模块 而 言 的 ，HTTP 框 染 还 是 需要 “尽职 尽责 ”地 接收 包 体 ， 在 接收 后 直接 丢弃 。 

















本 市 将 会 迪 到 一 个 问题 ， 这 个 问题 需要 用 请 求 ngx_http_request t 结 构 体 中 的 count 引 用 计 
数 解 决 。 举 个 例子 ，HTTP 模 块 在 处 理 请 求 时 ， 接 收 包 体 的 同时 可 能 还 需要 处 理 其 他 业务 ， 
如 使 用 upstream 机 制 与 另 一 台 服 务 器 通信 ， 这 样 两 个 动作 都 不 是 一 次 调度 可 以 完成 的 ， 它 们 
各 目 都 可 能 需要 多 次 调度 才能 完成 ， 那 么 在 其 中 一 个 动作 出 现 错误 导致 请 求 失败 时 ， 如 果 销 
毁 请 求 可 能 会 导致 另 一 个 动作 出 现 严重 错误 ， 怎 么 办 ? 这 时 就 需要 用 到 引用 计数 了 。 





在 HTTP 模块 中 每 进行 一 类 新 的 操作 ， 包 括 为 一 个 请 求 添加 新 的 事件 ， 或 者 把 一 些 已 经 
由 定时 器 、epoll 中 移 除 的 事件 重新 加 入 其 中 ， 都 需要 把 这 个 请 求 的 引用 计数 加 1。 这 是 因为 
需要 让 HTTP 框 架 知 道 ，HTTP 模 块 对 于 该 请 求 有 独立 的 异步 处 理 机 制 ， 将 由 该 HTTP 模 块 决 
定 这 个 操作 什么 时 候 结束 ， 防 止 在 这 个 操作 还 未 结束 时 HTTP 框 架 却 把 这 个 请 求 销毁 了 “如 
其 他 HTTP 模 块 通过 调用 ngx http finalize request 方 法 要 求 HTTP 框 架 结 束 请 求 ) ， 导 致 请 求 出 
现 不 可 知 的 严重 错误 。 这 就 要 求 每 个 操作 在 “认为 "自身 的 动作 结束 时 ， 都 得 最 终 调用 到 
ngx_http_close request 方法 ， 该 方法 会 自动 检查 引用 计数 ， 当 引用 计数 为 0 时 才 真正 地 销毁 请 
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求 。 实 际 上 ， 很 多 结束 请 求 的 方法 最 后 一 定 会 调用 到 ngx_ http _ close _ request 方法 〈 人 参见 
11.10.3 节 ) 。 





由 于 HTTP 包 体 是 可 变 长 度 的 ， 接 收 包 体 可 能 导致 HTTP 框 架 将 TCP 连 接 上 的 读 事件 再 次 
添加 到 epoll 和 定时 器 中 ， 表 示 和 希望 事件 驱动 机 制 发 现 TCP 连 接 上 接收 到 全 部 或 者 部 分 HITP 
包 体 时 ， 回 调 相 应 的 方法 读 取 套 接 字 缓冲 区 上 的 TCP 流 ， 这 时 必须 把 请 求 的 引用 计数 加 1， 
这 在 图 11-13 的 第 1 步 中 就 可 以 看 到 。 类 似 的 ， 在 第 5$ 章 介绍 的 subrequest 子 请 求 的 使 用 方法 
中 ， 派 生子 请 求 也 是 独立 的 动作 ， 它 会 向 epoll 和 定时 器 中 添加 新 的 事件 ， 引 用 计数 也 会 加 
1， 而 upstream 试 图 连接 新 的 服务 器 ， 它 同样 也 需要 把 当前 请 求 的 引用 计数 加 1。 当 这 类 操作 
结束 时 ， 如 HTTP 包 体 全 部 接收 完毕 时 ， 务 必 调 用 或 者 间接 地 调用 ngx http_close_ request 方 
法 ， 把 引用 计数 减 1， 这 才能 使 引用 计数 机 制 正常 工作 。 


@@ 注意 “引用 计数 一 般 都 作用 于 这 个 请 求 的 原始 请 求 上 ， 因 此 ， 在 结束 请 求 时 统一 检 
查 原 始 请 求 的 引用 计数 就 可 以 了 。 当 然 ， 目 前 的 HTTP 框 架 也 要 求 我 们 必须 这 样 做 ， 因 为 
ngx_http_close_fequest 方 法 只 是 把 原始 请 求 上 的 引用 计数 减 1。 对 应 到 代码 就 是 操作 f->main- 


>count 成 员 ， 其 中 t 是 请 求 对 应 的 ngx_http_request_t 结 构 体 。 


下 面 来 看 看 HTTP 框 架 提供 的 方法 是 如 何 使 用 的 ， 接 收 包 体 的 方法 其 实在 3.6.4 节 中 已 经 
讲 过 ， 再 来 回顾 一 下 。 








ngx int t ngx http read client request body(ngx httpP request t *r, ngx http client body handler pt post handler 

















调用 了 ngx http read_client request body 方 法 就 相当 于 启动 了 接收 包 体 这 一 动作 ， 在 这 个 
动作 完成 后 ， 就 会 回调 HTTP 模 块 定义 的 post_ handler 方 法 。post handler 是 一 个 函数 指针 ， 如 
下 所 示 。 





typedef void (*ngx http client body handler pt) (ngx http request 七 *r); 








而 决定 丢弃 包 体 时 ，HTTP 框 染 提 供 的 方法 是 ngx http_discard_request body， 如 下 所 示 。 
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ngx _ int t ngx http discard _ request body(ngx http request 七 *r) 








当然 ， 它 是 不 需要 再 让 HTTP 模 块 定义 类 似 post_handler 的 回调 方法 的 ， 当 丢弃 包 体 后 ， 
HTTP 框 架 会 自动 调用 ngx http finalize request 方 法 把 引用 计数 减 1， 详 见 11.8.2 节 。 


在 11.8.1 节 中 将 会 讨论 HTTP 框 架 是 怎样 实现 ngx http read client request body 方 法 的 ， 而 
在 11.8.2 节 中 则 会 讨论 ngx http_discard request body 方 法 的 实现 ， 由 于 这 两 个 方法 都 需要 被 事 
件 框架 多 次 调度 ， 学 习 它 们 的 设计 方法 可 以 帮助 我 们 开发 高 效 的 Nginx 模 块 。 


11.8.1 接收 包 体 


在 讨论 ngx http read client request body 方 法 的 实现 方式 前 ， 先 来 看 一 下 用 于 保存 HTTP 
包 体 的 结构 体 ngx http request body t， 如 下 所 示 。 





typedef struct { 
// 存放 


HTTP 包 体 的 临时 文件 


ngx temp file 七 temp file; 
/接收 








HTTP 包 体 的 缓冲 区 链表 。 当 包 体 需要 全 部 存放 在 内 存 中 时 ， 如 果 一 块 


ngx_buf 七 缓冲 区 无 法 存放 完 ， 这 时 就 需要 使 用 


ngx_chain 七 链表 来 存放 


/ 
ngx chain t bufs; 
// 直接 接收 

HTTP 包 体 的 缓存 


ngx buf 七 buf; 
/根据 


content-length 头 部 和 已 接收 到 的 包 体 长 度 ， 计 算出 的 还 需要 接收 的 包 体 长 度 
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off t rest; 
// 该 缓冲 区 链表 存放 着 将 要 写 入 文件 的 包 体 


ngx chain 七 *to write; 
/*HTTP 包 体 接收 完毕 后 执行 的 回调 方法 ， 也 就 是 





ngx http read client request body 方 法 传递 的 第 





2 个 参数 


ngx http client body handler pt post handler; 
} ngx http request body t; 











这 个 ngx_http_request_body tt 结构 体 就 存放 在 保存 着 请 求 的 ngx_http_request t 结 构 体 的 
request_body 成 员 中 ， 接 收 HTTP 包 体 就 是 围绕 着 这 个 数据 结构 进行 的 。 


上 文 说 过 ， 在 接收 较 大 的 包 体 时 ， 无 法 在 一 次 调度 中 完成 。 通 俗 地 讲 ， 就 是 接收 包 体 不 
是 调用 一 次 ngx_http_read_client request body 方法 就 能 完成 的 。 但 是 HTTP 框架 希望 对 于 它 的 
用 户 ， 也 就 是 HITP 横 块 而 言 ， 接 收 包 体 时 只 需要 调用 一 次 ngx_http_ read_client request body 
方法 就 好 ， 这 时 就 需要 有 另 一 个 方法 在 ngx http read _client request_ body 没 接收 到 完整 的 包 体 
时 ， 如 果 连 接 上 再 次 接收 到 包 体 就 被 调用 ， 这 个 方法 就 是 
ngx http read client request body handler。 











ngx_http read client request body handler 方 法 对 于 HTTP 模 块 是 不 可 见 的 ， 它 在 “幕后 ” 工 
作 。 当 继续 接收 发 自 客户 端的 包 体 时 ， 将 由 它 来 处 理 。 可 见 ， 它 与 
ngx_http_read_client request _ body 方法 有 很 多 共通 之 处 ， 它 们 都 会 去 试图 读 取 连 接 套 接 字 上 的 
绥 冲 区 ， 把 它们 共性 的 部 分 提取 出 来 构成 ngx_http_do_read_client_request_body 方 法 ， 它 负责 
具体 的 读 取 包 体 工作 。 本 节 的 内 容 就 在 于 说 明 这 3 个 方法 的 流程 。 








图 11-13 为 ngx http read client request body 方 法 的 流程 图 ， 在 该 图 中 同时 可 以 看 到 
ngx http_request t 结 构 体 中 的 request body 成 员 是 如 何 分 配 和 使 用 的 。 


NNn httpo://ww linuxorobe. con 









1) 原始 请 求 的 引用 计数 加 1 
[检查 是 否 操作 过 请 求 的 包 体 ] 







3 ) 分 配 用 于 接收 包 体 的 


request_body 成 员 


[检查 请 求 的 content-length 头 部 ] 


[已 经 做 过 放弃 包 体 或 者 接收 包 体 的 操作 ] 


[content_length 小 于 或 等 于 0] 





[content length 大 于 0] 


4) 设置 接收 完全 部 包 体 后 的 





post_handler 回 调 方 法 
[检查 已 经 读 取 到 的 包 体 长 度 ] 


[已 接收 到 的 包 体 长 度 大 于 或 等 于 content_length] 


[还 没有 接收 到 全 部 的 包 体 , 检查 headerin 缓冲 区 是 否 可 接收 全 部 包 体 ] 





[headerin 绥 冲 区 无 法 存放 全 部 包 体 ] 


2 ) 调用 HTTP 模 块 要 求 回调 的 





[接收 头 部 的 header_jin 缓 冲 区 可 以 存放 完整 的 包 体 ] post_handler 方 法 


5 ) 在 request_body 


上 分 配 用 于 接收 包 体 的 缓冲 区 


6) 设置 后 续 接 收 连接 上 TCP 流 的 


read_event_ handler 方 法 


7 ) 调用 ngx_do_read_client_request_body 


方法 接收 包 体 
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图 11-13 ngx_http_read_client_request_body 方 法 的 流程 图 


图 11-13 把 ngx_http read_client request_ body 方法 的 主要 流程 概括 为 7 个 步 又， 下 面 详细 说 
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明 一 下 。 





1) 首先 把 该 请 求 对 应 的 原始 请 求 的 引用 计数 加 1。 这 同时 是 在 要 求 每 一 个 HTTP 模 块 在 
传 入 的 post handler 方 法 被 回调 时 ， 务 必 调 用 类 似 ngx http finalize request 的 方法 去 结束 请 
求 ， 否 则 引用 计数 会 始终 无 法 清 零 ， 从 而 导致 请 求 无 法 释放 。 


检查 请 求 ngx http_ request t 结 构 体 中 的 request_ body 成 员 ， 如 果 它 已 经 被 分 配 过 了 ， 证 明 
已 经 读 取 过 HTTP 包 体 了 ， 不 需要 再 次 读 取 一 遍 ， 这 时 跳 到 第 2 步 执行 ， 再 检查 请 求 
ngx_http_ request t 结 构 体 中 的 discard_ body 标志 位 ， 如 果 discard_ body 为 1， 则 证 明 曾 经 执行 过 
丢弃 包 体 的 方法 ， 现 在 包 体 正 在 被 丢弃 中 ， 仍 然 跳 到 第 2 步 执行 。 只 有 这 两 个 条 件 都 不 满 
足 ， 才 说 明 真 正 需要 接收 HTTP 包 体 ， 这 时 跳 到 第 3 步 执行 。 








2) 这 一 步 将 直接 执行 各 HTTP 模 块 提供 的 post_handler 回 调 方 法 ， 接 着 ， 
ngx http read client request body 方 法 返回 NGX OK。 


3) 分 配 请 求 的 ngx http request t 结 构 体 中 的 request_body 成 员 (之 前 request_body 是 NULL 
空 指针 ) ， 准 备 接收 包 体 。 


4) 检查 请 求 的 content-length 头 部 ， 如 果 指 定 了 包 体 长 度 的 content-length 字 段 小 于 或 等 于 
0， 当 然 不 用 继续 接收 包 体 ， 跳 到 第 2 步 执行 ， 如果 content-length 大 于 0， 则 意味 着 继续 执行 ， 
但 HTTP 模块 定义 的 post_handler 方 法 不 会 知道 在 哪 一 次 事件 的 触发 中 会 被 回调 ， 所 以 先 把 它 
设置 到 request_ body 结构 体 的 post handler 成 员 中 。 











5) 注意 ， 在 11.5 节 描述 的 接收 HTTP 头 部 的 流程 中 ， 是 有 可 能 接收 到 HTTP 包 体 的 。 首 先 
我 们 需要 检查 在 header in 缓冲 区 中 已 经 接收 到 的 包 体 长 度 ， 确 定 其 是 否 大 于 或 者 等 于 content- 
length 头 部 指定 的 长 度 ， 如 果 大 于 或 等 于 则 说 明 已 经 接收 到 完整 的 包 体 ， 这 时 跳 到 第 2 步 执 


/一 


休 。 





当 上 述 条 件 不 满足 时 ， 再 检查 header in 缓冲 区 里 的 剩余 空闲 空间 是 否 可 以 存放 下 全 部 的 
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包 体 〈content-length 头 部 指定 ) ， 如 果 可 以 ， 就 不 用 分 配 新 的 包 体 缓冲 区 溪 费 内 存 了 ， 直 接 
跳 到 第 6 步 执 行 。 





当 以 上 两 个 条 件 都 不 满足 时 ， 说 明确 实 需 要 分 配 用 于 接收 包 体 的 缓冲 区 了 。 绥 冲 区 长 度 
由 nginx.conf 文 件 中 的 client_body_buffer_size 配 置 项 指定 ， 绥 冲 区 就 在 ngx_http_request body t 
结构 体 的 buf 成 员 中 存放 着 ， 同 时 ，bufs 和 to _write 这 两 个 缓冲 区 链表 首部 也 指向 该 buf。 


6) 设置 请 求 ngx_http_request 结构 体 的 read_event_handler 成 员 为 上 面 介 绍 过 的 
ngx_http_read client request body handler 方 法 ， 它 意味 着 如 果 epoll 再 次 检测 到 可 读 事 件 或 者 
读 事 件 的 定时 器 超时 ，HTTP 框 架 将 调用 ngx http read client request body handler 方 法 处 理 ， 
该 方法 所 做 的 工作 参见 图 11-15。 

7) 调用 ngx_http_do_read_client_request_body 方 法 接收 包 体 。 该 方法 的 意义 在 于 把 客户 端 
与 Nginx 之 间 TCP 连 接 上 套 接 字 绥 冲 区 中 的 当前 字符 流 全 部 读 出 来 ， 并 判断 是 否 需要 写 入 文 
件 ， 以 及 是 否 接 收 到 全 部 的 包 体 ， 同 时 在 接收 到 完整 的 包 体 后 激活 post_handler 回 调 方法 ， 如 
图 11-14 所 示 。 
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[检查 request oO 接收 包 体 缓冲 区 ] 







[缓冲 区 写 满 ] 
[缓冲 区 上 还 有 空闲 空间 ] 
1 ) 将 绥 冲 区 中 数据 
写 人 临时 文件 


2) 重 置 ngxbuf t+ 缓冲 区 里 的 

os 、last 参数 
[ 仍 有 可 接收 的 字符 流 ] 
3) 将 TCP 连 接 套 接 字 上 的 


字符 流 读 取 到 缓冲 区 
[检查 recv 方 法 的 返回 值 ] 


[出 现 错误 或 者 客户 端 关 闭 了 连接 ] 


[接收 到 字符 流 ] 


4) 设置 error 标 志 位 为 1， 


5 ) 根据 接收 内 容 修 改 es 
缓冲 区 的 last 参 数 返回 错误 码 4 
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[已 接收 到 全 部 的 包 体 ,检查 定时 器 中 是 和 否 还 在 监控 读 事件 ] 





[ 套 接 字 缓冲 区 中 没有 可 读数 据 ] 


6) 将 读 事件 添加 





到 定时 器 
[ 读 事 件 还 在 定时 器 中 ] | 读 事 件 不 在 定时 器 中 ] 


8 ) 将 读 事 件 从 定时 需 
中 删除 7 ) 将 读 事 件 添加 到 epoll 
并 返回 NGX_AGAIN 


9) 将 绥 冲 区 剩余 内 容 
写 入 临时 文件 


10) 重新 设置 后 续 接 收 连 接 上 TCP 流 的 


11) 调用 HTTP 模 块 要 求 回 调 的 
yost_handle! 方 法 





图 11-14 ngx_http_do_read_client_request_body 方 法 的 流程 图 
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图 11-14 中 列 出 的 ngx http do read client request body 方 法 流程 稍 显 复杂 ， 下 面 详细 解释 


一 下 这 11 个 步骤。 


1) 首先 检查 请 求 的 request_ body 成 员 中 的 buf 缓 冲 区 ， 如 果 绥 名 区 还 有 空闲 的 空间 ， 则 跳 
到 第 3 步 读 取 内 核 中 套 接 字 缓冲 区 里 的 TCP 字 符 流 ;如 果 缓 冲 区 已 经 写 满 ， 则 调用 
ngx_http_wWrite_ request _ body 方法 把 缓冲 区 中 的 字符 流 写 入 文件 。 


2) 通过 第 1 步 把 request_ body 缓冲 区 中 的 内 容 写 入 文件 后 ， 绥 冲 区 就 可 以 重复 使 用 了 ， 
只 需要 把 缓冲 区 ngx buf tt 结构 体 的 last 指 针 指向 start 指 针 ， 缓 冲 区 即 可 复 用 。 


3) 调用 封装 了 recv 的 方法 从 套 接 字 缓冲 区 中 读 取 包 体 到 缓冲 区 中 。 如 果 recv 方 法 返回 错 
误 ， 或 者 客户 端 主动 关闭 了 连接 ， 则 路 到 第 4 步 执行 ， 如果 读 取 到 内 容 ， 则 跳 到 第 5 步 执行 。 


4) 设置 negx http _ request t 结 构 体 的 error 标 志 位 为 1!， 同 时 返回 
NGX HTTP BAD REQUEST 错 误 人 码 。 


5) 根据 接收 到 的 TCP 流 长 度 ， 修 改 缓冲 区 参数 。 例 如 ， 把 缓冲 区 ngx buf t 结 构 体 的 last 
指针 加 上 接收 到 的 长 度 ， 同 时 更 新 request _ body 结构 体 中 表示 竺 接收 的 剩余 包 体 长 度 的 rest 成 
员 、 更 新 ngx_http_ request t 结 构 体 中 表示 已 接收 请 求 长 度 的 request length 成 员 。 


根据 rest 成 员 检 查 是 人 否 接收 到 完整 的 包 体 ， 如 果 接 收 到 了 完整 的 包 体 ， 则 路 到 第 8 步 继 续 
执行 ， 人 否则 奉 看 套 接 字 缓冲 区 上 是 人 否 仍然 有 可 读 的 字符 流 ， 如 果 有 则 跳 到 第 1 步 继续 接收 包 
体 ， 如 果 没 有 则 跳 到 第 6 步 。 





6) 如 果 当 前 已 经 没有 可 读 的 字符 流 ， 同 时 还 没有 接收 到 完整 的 包 体 ， 则 说 明 需 要 把 读 
事件 添加 到 事件 模块 ， 等 待 可 读 事件 发 生 时 ， 事 件 框架 可 以 再 次 调度 到 这 个 方法 接收 包 体 。 
这 一 步 是 调用 ngx_add_timer 方 法 将 读 事件 添加 到 定时 器 中 ， 超 时 时 间 以 nginx.conf 文 件 中 的 
client body timeout 配 置 项 参数 为 准 。 
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ngx http do read client request body 方 法 结束 ， 返 回 NGX _ AGAIN。 


8) 到 这 一 步 ， 表 明 已 经 接收 到 完整 的 包 体 ， 需 要 做 一 些 收 尾 工 作 了 。 首 先 不 需要 检查 
是 否 接 收 HTTP 包 体 超时 了 ， 要 把 读 事 件 从 定时 器 中 取出 ， 防 止 不 必要 的 定时 器 触发 。 这 一 
步 会 检查 读 事 件 的 timer_ set 标志 位 ， 如 果 为 1， 则 调用 ngx del timer 方 法 把 读 事 件 从 定时 右 中 





9) 如 果 缓 冲 区 中 还 有 未 写 入 文件 的 内 容 ， 调 用 ngx http write_request_body 方 法 把 最 后 
的 包 体 内 容 也 写 入 文件 。 


10) 在 图 11-13 的 第 5 步 中 曾经 把 请 求 的 read_event handler 成 员 设 置 为 
ngx http read client request body handler 方 法 ， 现 在 既然 已 经 接收 到 完整 的 包 体 了 ， 束 会 把 
read event handler 设 为 ngx http block reading 方 法 ， 表 示 连 接 上 再 有 读 事 件 将 不 做 任何 处 
理 O 





11) 执行 HTTP 模 块 提供 的 post_handler 回 调 方法 后 ，ngx_http_do _read client request_ body 
方法 结束 ， 返 回 NGX_OK。 


图 11-13 中 的 第 6 步 把 请 求 的 read_event handler 成 员 设 置 为 
ngx_http_ read _ client request body handler 方 法 ， 从 11.6 节 的 图 11-7 可 以 看 出 ， 这 个 请 求 连接 上 
的 读 事件 触发 时 的 回调 方法 negx http request handler 会 调用 read event handler 方 法 ， 下 面 根 据 
图 11-15 来 看 看 这 时 ngx http read client request body handler 方 法 做 了 些 什 么 。 
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[ 读 事件 未 超时 ] 


[ 读 事件 已 经 超时 ] 


1 ) 调用 ngx_http_finalize _request 


结束 请 求 并 发 送 408 啊 应 





2 ) 调用 ngx_http_do _read_client _request_body 方 法 接收 包 体 


[检查 方法 返回 值 ] 





[返回 值 大 于 或 等 于 300] 


3) 以 上 一 步 返回 值 为 参数 调用 
ngx_http _finalize_request 结束 请 求 





© 


图 11-15 ngx_http_read_client_request_body_handlet 方 法 的 流程 图 


简单 解释 一 下 图 11-15 中 的 3 个 步骤 。 


1) 首先 检查 连接 上 读 事 件 的 tmeout 标 志 位 ， 如 果 为 1， 则 表示 接收 HTTP 包 体 超时 ， 这 
时 把 连接 ngx_connection t 结 构 体 上 的 timeout 标 志 位 也 置 为 !， 同 时 调用 
ngx http finalize request 方 法 结束 请 求 ， 并 友 送 408 超 时 错误 码 。 如 果 没 有 超时 ， 则 跳 到 第 2 步 
执行 。 
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2) 调用 图 11-14 中 介绍 的 ngx http do read _ client request body 方 法 接收 包 体 ， 检 测 这 个 
方法 的 返回 值 ， 如 果 它 大 于 300， 那 么 一 定 表 示 和 希望 返回 错误 码 。 例 如 ， 图 11-14 的 第 4 步 就 
返回 了 400 错 误 码 ， 这 时 跳 到 第 3 步 执行 ， 人 否则 ngx_http_read_client_ request _ body_handler 方 法 
结束 ， 直 接 返 回 NGX_OK。 


3) 调用 ngx_http finalize request 方法 结束 请 求 ， 第 2 个 参数 传递 的 是 
ngx http do read client request body 方 法 的 返回 值 ， 详 见 11.10.6 节 。 


以 上 3 个 方法 完整 地 描述 了 HTTP 框 架 接收 包 体 的 流程 ， 以 及 最 后 如 何 执行 HTTP 模 块 实 
现 的 post_handler 方 法 。 读 者 可 以 参照 它 再 看 看 第 3 章 中 开发 HTTP 模 块 时 是 如 何 接收 包 体 的 ， 
相信 经 过 本 章 的 分 析 ， 读 者 会 对 这 一 机 制 有 新 的 认识 。 








11.8.2 ”放弃 接收 包 体 








对 于 HTTP 模 块 而 言 ， 放 弃 接 收 包 体 就 是 简单 地 不 处 理 包 体 了 ， 可 是 对 于 HTTP 框 染 而 
言 ， 并 不 是 不 接收 包 体 就 可 以 的 。 因 为 对 于 客户 端 而 言 ， 通 常会 调用 一 些 阻塞 的 发 送 方法 来 
发 送 包 体 ， 如 果 HTTP 框 架 一 直 不 接收 包 体 ， 会 导致 实现 上 不 够 健壮 的 客户 端 认 为 服务 器 超 
时 无 响应 ， 因 而 简单 地 关闭 连接 ， 可 这 时 Nginx 模 块 可 能 还 在 处 理 这 个 连接 。 因 此 ，HTTP 模 
块 中 的 放弃 接收 包 体 ， 对 HTTP 框 架 而 言 就 是 接收 包 体 ， 但 是 接收 后 不 做 保存 ， 直 接 丢 弃 。 











HTTP 框 架 提供 了 一 个 方法 一 ngx http discard request body 用 于 丢弃 包 体 ， 使 用 上 也 非常 
简单 ， 直 接 调 用 这 个 方法 就 可 以 了 ， 不 像 11.8.1 节 中 接收 包 体 一 样 还 需要 一 个 回调 方法 。 下 
面 先 来 看 看 ngx http discard request body 方 法 的 定义 。 


ngx _ int t ngx http discard request body(ngx http request 七 *r) 











可 以 看 到 ， 它 是 没有 post handler 回 调 方法 的 ， 那 么 接收 完全 部 的 包 体 后 怎么 办 呢 ? 很 简 
单 ， 在 图 11-18 的 第 3 步 就 是 接收 到 全 部 包 体 后 的 动作 ， 其 代码 如 下 所 示 。 











~ 


ngx http finalize request(r, NGX DONE 





这 里 实际 上 相当 于 把 原始 请 求 的 引用 计数 减 1 了， 当然 ， 如 果 引 用 计数 为 0 如 HTTP 模 
块 已 经 调用 过 结束 请 求 的 方法 ) ， 还 是 会 真正 结束 请 求 的 。 








放弃 接收 包 体 和 接收 包 体 的 实现 方式 是 极其 相似 的 ， 它 也 使 用 了 3 个 方法 实现 ，HTTP 模 
块 调用 的 ngx_http_discard_request_body 方 法 用 于 第 一 次 启动 丢弃 包 体 动作 ， 而 
ngx_http_discarded_request_body_handler 是 作为 请 求 的 read_event handler 方 法 的 ， 在 有 新 的 可 
读 事 件 时 会 调用 它 处 理 包 体 。ngx_http_ read discarded request body 方 法则 是 根据 上 述 两 个 方 
法 通用 部 分 提取 出 的 公共 方法 ， 用 来 读 取 包 体 且 不 做 任何 处 理 。 








下 面 看 看 ngx http_ discard request body 方 法 做 了 些 什 么 ， 如 图 11-16 所 示 。 





F 面 解释 一 下 图 11-16 中 所 列 的 7 个 步骤 。 

















1) 首先 检查 当前 请 求 是 一 个 子 请 求 还 是 原始 请 求 。 为 什么 要 检查 这 个 呢 ? 因为 对 于 子 
请 求 而 言 ， 它 不 是 来 目 客户 端的 请 求 ， 所 以 不 存在 处 理 HITP 请 求 包 体 的 概念 。 如 果 当 前 请 
求 是 原始 请 求 ， 则 跳 到 第 2 步 中 继续 执行 ， 如 果 和 它 是 子 请求， 则 直接 返回 NGX_OK 表 示 丢 弃 
包 体 成 功 。 








2) 检查 请 求 连 接 上 的 读 事 件 是 否 在 定时 器 中 ， 这 是 因为 丢弃 包 体 不 用 考虑 超时 间 题 
Clinger_timer 例 外 ， 本 章 不 考虑 此 情况 ) 。 如 果 读 事件 的 timer_set 标 志 位 为 1， 则 从 定时 器 中 
移 除 此 事件 。 还 要 检查 contentlength 头 部 ， 如 果 筷 的 值 小 于 或 等 于 0， 同 样 意味 痢 可 以 直接 返 
回 NGX OK， 表示 成 功 丢 大 了 全 部 包 体 。 或 者 检查 ngx http request t 结 构 体 的 request_body 成 
员 ， 如 果 乞 已经 被 赋值 过 且 不 再 为 NULL 空 指针， 则 说 明 已 经 接收 过 包 体 了 ， 这 时 也 需要 返 


回 NGX_OK 表 示 成 功 。 











3) 就 像 11.8.1 节 中 介绍 的 那样 ， 在 接收 HTTP 头 部 时 ， 还 是 要 检查 是 否 凌 巧 已 经 接收 到 
完整 的 包 体 〈 如 果 包 体 很 小 ， 那 么 这 是 非常 可 能 发 生 的 事 ) ， 如 果 已 经 接收 到 完整 的 包 体 ， 
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则 跳 到 第 1 步 直 接 返 回 NGX_OK， 表 示 丢 弃 包 体 成 功 ， 人 否则， 说 明 需 要 多 次 的 调度 才能 完成 
丢弃 包 体 这 一 动作 ， 此 时 把 请 求 的 read_event handler 成 员 设置 为 
ngx http discarded request body handler 方 法 。 
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[检查 当前 请 求 是 否 可 以 放弃 包 体 ] 





[检查 连接 上 的 读 事 件 是 否 在 定时 融 中 ] 
[当前 请 求 不 是 原始 请 求 , 或 者 包 体 已 经 丢弃 ] 





[ 读 事 件 在 定时 器 中 ] 


[ 读 事件 不 在 定时 器 中 ] 2 ) 将 读 事件 从 








定时 需 中 移 除 
[检查 content- length 头 部 ] 





[content_length 小 于 或 等 于 0, 或 者 已 经 接收 过 包 体 ] 


[检查 header_in 绥 冲 区 ] 







[ 在 header in 缓冲 区 里 接收 到 完整 的 包 体 ] 


[header_ in 缓冲 区 中 未 接收 到 完整 包 体 ] 























3) 设置 后 续 接 收 连接 上 


TCP 流 的 read_event_handler 方 法 回 NGX_OK 


[at 
[| 
| 









4) 将 读 事件 
深 加 到 epoll 中 


5 ) 调用 ngx_http_read_discarded_request_body 
接收 包 体 并 丢弃 
[检查 方法 的 返回 值 ] 






[返回 NGX_OK] 
[返回 韭 NGX_OK] 


6 ) count 引 用 计数 加 1 
并 返回 NGX_OK 


7) 设置 延迟 关闭 标志 位 为 0 
并 返回 NGX _OK 


站 中 口 口 站 生生 入 站 时 ET Xr obe., con 





4) 调用 ngx handle read_event 方 法 把 读 事件 谎 加 到 epoll 中 。 


5) 调用 ngx http read discarded request body 方 法 接收 包 体 ， 检 测 它 的 返回 值 。 如 果 返 
回 NGX_ OK， 则 跳 到 第 7 步 ， 人 否则 跳 到 第 6 步 。 








6) 返回 非 NGX_OK 表 示 Nginx 的 事件 框架 触发 事件 需要 多 次 调度 才能 完成 丢弃 包 体 这 一 
动作 ， 于 是 先 把 引用 计数 加 1， 防 止 这 边 还 在 丢 径 包 体 ， 而 其 他 事件 却 已 让 请 求 意 外 销毁 ， 
引发 严重 错误 。 同 时 把 ngx_ http_ request tt 结构 体 的 discard_body 标 志 位 置 为 !， 表 示 正 在 丢弃 
包 体 ， 并 返回 NGX_OK， 当 然 ， 这 时 的 NGX_OK 绝 不 表示 已 经 成 功 地 接收 完 包 体 ， 只 是 说 明 
ngx _http_ discard request_ body 执行 完毕 而 已 。 








7) 返回 NGX_OK 表 示 已 经 接收 到 完整 的 包 体 了 ， 这 时 将 请 求 的 lingering_close 延 时 关闭 
标志 位 设 为 0， 表 示 不 需要 为 了 包 体 的 接收 而 延 时 关闭 了 ， 同 时 返回 NGX_OK 表 示 丢 弃 包 体 
成 功 。 





从 以 上 步骤 可 以 看 出 ， 当 ngx http discard request body 方法 返回 NGX OK 时 ， 是 可 能 
达 很 多 意思 的 。HTTP 框 架 的 目的 是 希望 各 个 HTTP 模块 不 要 去 关心 丢弃 包 体 的 执行 情况 ， 这 
些 工作 完全 由 HTTP 框架 完成 。 





下 面 再 看 看 在 第 5 步调 用 的 ngx http read discarded request body 方法 的 执行 流程 ， 如 图 
11-17 所 示 。 
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[检查 还 需要 接收 的 包 体 长 度 headers_in.content_length_n| 









[丢弃 的 包 体 长 度 已 经 达到 content-length 指 定 长 度 ] 


S 


[还 有 包 体 需要 处 理 ] 






1) 设置 后 续 接 收 连接 上 TCP 流 的 
read_event handle 访 法 





[ 套 接 字 缓 冲 区 上 没有 可 读 内 容 ] 
[ 套 接 字 上 有 可 读 TCP 流 ] 


3) 直 TCP 连 接 的 套 接 字 缓 证 区 
中 读 取 请 求 的 包 体 
[检查 recv 接收 方法 的 返回 值 ] 

[ 套 接 字 缓冲 区 已 空 







需要 继续 读 取 包 体 ] 2) 返回 


NGX _AGAIN 















[客户 端 关闭 了 连接 ] 


5 ) 更 新 已 经 丢弃 
的 包 体 长 度 


图 11-17 ngx_http_read_discarded_request_body 方 法 的 流程 图 


可 以 看 到 ， 虽 然 ngx http read discarded request body 方法 与 
ngx_http_do_read_client request_body 方 法 很 类 似 ， 但 前 者 比 后 者 简单 多 了 ， 毕 竞 不 需要 保存 
接收 到 的 包 体 。 下 面 简 单 分 析 一 下 图 11-17 中 的 5 个 步 又 。 








1) 丢弃 包 体 时 请 求 的 request_ body 成 员 实 际 上 是 NULL 空 指针 ， 那 么 用 什么 变量 来 表示 
己 经 丢弃 的 包 体 有 多 大 呢 ? 实际 上 这 时 使 用 了 请 求 ngx http request t 结 构 体 headers in 成 员 里 
的 content length n， 最 初 它 等 于 content-length 凑 部 ， 而 每 丢弃 一 部 分 包 体 ， 就 会 在 
content length n 变 量 中 减 去 相应 的 大 小 。 因 此 ，content length n 表 示 还 需要 丢弃 的 包 体 长 
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度 ， 这 里 首先 检查 请 求 的 content_length_n 成 员 ， 如 果 它 已 经 每 于 0， 则 表示 已 经 接收 到 完整 的 
包 体 ， 这 时 要 把 read event handler 重 置 为 ngx http block reading 方 法 ， 表 示 如 果 再 有 可 读 事 
件 被 触发 时 ， 不 做 任何 处 理 。 同 时 返回 NGX _ OK， 告诉 上 层 的 方法 已 经 丢弃 了 所 有 包 体 。 


2) 如 果 连 接 套 接 字 的 缓冲 区 上 没有 可 读 内 容 ， 则 直接 返回 NGX AGAIN， 告 诉 上 层 方 
法 需要 等 待 读 事件 的 触发 ， 等 待 Nginx 框 架 的 再 次 调度 。 








3) 调用 recv 方 法 读 取 包 体 。 根 据 返回 值 确定 ， 如 果 套 接 字 缓冲 区 中 没有 该 取 到 内 容 ， 
而 需要 继续 读 取 则 跳 到 第 2 步 ， 如 果 客 户 端 主动 天 闭 了 连接 ， 则 跳 到 第 4 步 ， 如 果 读 取 到 了 内 


容 ， 则 跳 到 第 5 步 。 





4) 既然 客户 端 主动 关闭 了 连接 ， 直 接 返 回 NGX OK 告诉 上 层 方法 结束 丢弃 包 体 动作 即 
可 。 





5) 接收 到 包 体 后 ， 要 更 新 请 求 的 content length_n 成 员 (参见 第 1 步 中 的 描述 ) ， 同 时 再 
跳 回 到 第 1 步 准备 再 次 接收 包 体 。 











最 后 再 看 看 请 求 的 ngx handle read event 指 定 的 ngx http_discarded request body handler 
方法 ， 在 新 的 可 读 事 件 被 触发 时 ，HTTP 框 架 将 会 调用 它 来 处 理事 件 ， 图 11-18 给 出 了 该 方法 
的 流程 。 
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[检查 连接 上 的 读 事 件 是 否 超时 | 
[已 经 接收 请 求 超时 ] 















1 ) 调用 ngx_http_finalize 


方法 结束 请 求 


_redquest 





[接收 请 求 未 超时 ] 


2 ) 调用 ngx_http_read_discarded_request_body 
方法 接收 包 体 
[ 检查 方法 的 返回 值 ] 

[返回 值 是 NGX _OK] 









3 ) 调用 ngx_http_finalize_request 


方法 天 结束 请 求 ， 参 数 为 NGX_DONE 





) 将 读 事 件 添 加 到 epoll 中 





图 11-18 hgx_http_discarded_tfequest_body_handletr 方 法 的 流程 图 













实际 上 ，ngx http discarded request body handler 方 法 还 涉及 lingering time 的 处 理 ， 为 了 
减少 非 主干 内 容 的 篇 幅 ， 本 章 将 不 涉及 此 内 容 ， 因 此 图 11-18 中 也 没有 给 出 。 下 面 分 析 一 下 


图 11-18 中 的 4 个 步 又; 


1) 首先 检查 TCP 连 接 上 的 读 事 件 的 timedout 标 志 位 ， 为 1 时 表示 已 经 超时 ， 这 时 调用 


ngx_http_finalize_ request 方法 结束 请 求 ， 传 递 的 参数 是 NGX_ERROR， 流 程 结 


2) 调用 ngx http read discarded request body 方法 接收 包 体 ， 检 测 其 返回 值 。 如 果 返 回 


NGX_ OK， 则 跳 到 第 3 步 执 行 ， 否 则 跳 到 第 4 步 





3) 此 时 表示 已 经 成 功 地 丢弃 完 所 有 的 包 体 ， 这 一 步骤 将 请 求 的 正在 丢弃 包 体 
discard_ body 标志 位 置 为 0， 将 延迟 关闭 标志 位 lingering close 也 置 为 0， 再 调用 
ngx http finalize request 方法 结束 请 求 注 意 ， 它 的 第 2 个 参数 是 NGX DONE，11.10.6 节 将 
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会 让 


绍 NGX_DONE 参 数 引 发 的 动作 。 然 后 流程 结束 。 


4) 仍然 需要 调用 ngx handle read_event 方 法 把 读 事件 添加 到 epoll 中 ， 期 竺 新 的 可 读 事 件 
到 来 。 


以 上 介绍 了 丢弃 包 体 的 全 部 流程 ， 可 以 看 到 ， 这 个 简单 的 动作 其 实 也 需要 很 多 步骤 才能 
完成 ， 但 它 非 党 高 效 ， 没 有 任何 阻 豆 进程 ， 也 没有 让 进程 休眠 的 操作 。 同 时 ， 对 于 HTTP 模 
块 而 言 ， 它 使 用 起 来 也 比较 简单 ， 值 得 读者 学 习 。 
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11.9 发 送 HITP 响 应 





本 节 开 始 讨论 第 3 章 中 已 出 现 过 的 发 送 HTTP 响 应 的 两 个 方法 : ngx_http_send header 方 法 
和 ngx_http_output filter 方 法 。 这 两 个 方法 将 负责 把 HITP 响 应 中 的 应 答 行 、 头 部 、 包 体 发 送 给 
客户 端 。Nginx 是 一 个 全 异步 的 事件 驱动 架构 ， 那 么 仅仅 调用 ngx_http_send header 方 法 和 
ngx_http_output filter 方法， 就 可 以 把 响应 全 部 发 送 给 客户 端 吗 ? 当然 不 是 ， 当 响应 过 大 无 法 
一 次 发 送 完 时 〈TCP 的 滑动 窗口 也 是 有 限 的 ， 一 次 非 阻 塞 的 发 送 多 半 是 无 法 发 送 完整 的 
HTTP 响 应 的 ) ， 就 需要 向 epoll 以 及 定时 器 中 添加 写 事件 了 ， 当 连接 再 次 可 写 时 ， 就 调用 
ngx_http_writer 方 法 继续 发 送 响 应 ， 直 到 全 部 的 响应 都 发 送 到 客户 端 为 止 。 











以 上 大 致 说 了 一 下 HTTP 框 架 为 发 送 响应 所 要 做 的 工作 ， 然 而 ， 对 于 各 个 HITP 模 块 而 
言 ， 绝 大 多 数 情况 下 发 送 HTTP 响 应 时 就 是 这 个 请 求 结束 的 时 候 ， 难 道 说 还 要 像 接 收 包 体 那 
样 ， 传 递 一 个 post handler 回 调 方法 ， 等 所 有 的 响应 都 发 送 完 时 再 回调 HTTP 模块 的 
post_handler 方 法 来 关闭 请 求 吗 ? 这 个 设计 显然 是 不 好 的 ， 根 据 HTTP 的 特点 ， 只 要 开始 发 送 
响应 基本 上 可 以 确定 请 求 就 要 结束 了 。 因 此 ，HTTP 采 用 的 设计 是 ， 使 用 ngx http output filter 
方法 发 送 响 应 时 ， 必 须 与 结束 请 求 的 ngx http finalize request 方法 配合 使 用 
(ngx http finalize request 方 法 会 把 请 求 的 write event handler 设 置 为 ngx http writer 方 法 ， 并 
将 写 事件 添加 到 epoll 和 定时 器 中 ) ， 这 样 就 使 得 真正 负责 在 后 台 异 步 地 发 送 啊 应 的 
ngx_http_writer 方 法 对 HTTP 模 块 而 言 也 是 透明 的 。 


11.9.1 市 中 将 介绍 发 送 HTTP 响 应 行 、 头 部 的 ngx_http_send_header 方 法 ，11.9.2 市 将 介绍 发 
送 响应 包 体 的 ngx_http_output filter 方 法， 同时 在 这 两 节 中 还 会 穿插 介绍 如 何 配合 
ngx_http_finalize request 方法 使 用 ， 实 现 异 步 的 发 送 机 制 。 最 后 在 11.9.3 节 会 介绍 在 后 台 发 送 
啊 应 的 negx http_ writer 方 法 。 








11.9.1 ngx http send header 
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ngx_http_send_header 方 法 负责 构造 HTTP 响应 行 、 头 部 ， 同 时 会 把 它们 发 送 给 客户 端 。 
发 送 响应 头 部 使 用 了 第 6 章 所 述 的 流水 线 式 的 过 滤 模 块 思想 ， 即 通过 提供 统一 的 接口 ， 让 各 
个 感 兴趣 的 HTTP 模 块 加 入 到 ngx_http send header 方 法 中 ， 然 后 通过 每 个 过 滤 模 块 C 源 文件 中 
独 有 的 ngx_http_next_header filter 指 针 将 各 个 过 滤 头 部 的 方法 连接 起 来 ， 这 样 ， 在 调用 
ngx_http send header 方 法 时 ， 实 际 就 是 依次 调用 了 所 有 头 部 过 滤 模 块 的 方法 ， 其 中 ， 链 表 里 
的 最 后 一 个 头 部 过 滤 方 法 将 负责 发 送 头 部 。 因 此 ， 这 些 过 滤 模 块 组 成 的 链表 顺序 是 非常 重要 
的 ， 我 们 在 第 6 章 的 6.2.1 节 和 6.2.2 节 已 经 介绍 过 这 部 分 内 容 ， 这 里 不 再 歼 述 。 




















调用 ngx_http send_ header 方 法 时 ， 最 后 一 个 头 部 过 滤 模 块 叫做 
ngx_http_header filter_ module 模块， 之 前 的 头 部 过 滤 模 块 会 根据 特性 去 修改 表示 请 求 的 
ngx_http_request_t 结 构 体 中 headers_out 成 员 里 的 内 容 ， 而 最 后 一 个 头 部 过 小 模 块 
ngx http header filter module 提 供 的 ngx http header filter 方 法 则 会 根据 HTTP 规 则 把 
headers_out 中 的 成 员 变 量 序列 化 为 字符 流 ， 并 发 送出 去 ， 而 本 节 的 重点 就 在 于 说 明 
ngx_http header filter 方 法 所 做 的 工作 。 











在 了 解 ngx_http_header filter 方 法 之 前 ， 我 们 还 是 得 先 回顾 一 下 事件 驱动 机 制 ， 因 为 它 要 
求 任何 操作 都 不 可 以 阻塞 进程 ，ngx_http header filter 方 法 当然 也 不 能 例外 。 那 么 ， 如 果 要 发 
送 的 响应 头 部 大 于 套 接 字 可 写 的 缓存 ， 无 法 一 次 把 响应 头 部 发 送出 去 怎么 办 ?这 就 需要 使 用 
ngx_http request t 结 构 体 中 ngx_chain t 关 型 的 成 员 out 了 ， 它 将 会 保存 没有 发 送 完 的 〈 剩 余 
的 ) 响应 头 部 。 那 么 ， 什 么 时 候 发 送 请 求 out 成 员 中 保存 的 剩余 响应 头 部 呢 ? 这 就 要 结合 
于 结束 请 求 的 ngx http finalize request 方法 来 说 了 。 

















当 ngx_http header filter 方法 无 法 一 次 性 发 送 HITP 头 部 时 ， 将 会 有 以 下 两 个 现象 同时 发 
生 。 


.请求 的 out 成 员 中 将 会 保存 剩余 的 响应 头 部 。 


ngx_http_header_filtet 方 法 返回 NGX_AGAIN。 
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如 果 这 个 啊 应 没有 包 体 ， 那 么 这 时 通常 已 经 可 以 调用 ngx http finalize request 方法 来 结束 
请 求 了 ， 参 见 11.10.6 节 中 ngx http finalize request 方 法 的 原型 ， 它 的 第 2 个 参数 很 关键 ,我们 
需要 把 NGX AGAIN 传 进去 ， 这 样 ngx http finalize request 方法 就 理解 了 实际 上 还 需要 HTTP 
框架 继续 发 送 请 求 out 成 员 中 保存 的 剩余 啊 应 字符 流 。ngx_http_finalize_request 方 法 会 设置 请 
求 的 write_event handler 成 员 为 ngx http writer 方法 ， 这 样 ， 当 连接 上 有 可 写 事件 时 ， 就 会 调 
用 11.9.3 节 描述 的 ngx http_writer 方 法 继续 发 送 剩 余 的 HITP 响 应。 下 面 先 来 看 看 
ngx_http_header filter 方 法 的 流程 图 ， 如 图 11-19 所 示 。 
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[检查 请 求 的 header_sent 标志 位 ] 





和 下 
[header_sent 标志 位 为 0 ] [ nenilem ,pent tis 


2. ) 将 header_sent 
标志 位 置 为 1 
[检查 当前 请 求 是 于 请 求 还 是 原始 请 求 ] 


[ 当前 请 求 不 是 上 1 始 吝 青 求 ] 








[ 当前 请 求 是 原始 请 求 , 再 检查 请 求 的 HTTP 版 本 ] 
[HTTP 版 本 小 于 1.0] 


[HTTP 版 本 为 1.0 或 者 1.1] 


3 ) 计算 啊 应 行 、 1) 返回 
头 部 序列 化 后 字符 流 长 度 NGX_OK 


4) 在 内 存 池上 分 配 用 于 
存放 响应 字符 流 的 缓存 


5 ) 将 啊 应 行 、 
头 部 按 规 则 序列 化 到 缓存 中 


6) 调 用 ngx_http_write_filter 
方法 发 送 构造 好 的 缓存 








时 
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下 面 描述 一 下 图 11-19 中 的 6 个 步骤 。 


1)〉 首 先 检查 请 求 ngx_http_request t 结 构 体 的 header_ sent 标 志 位 ， 如 果 header sent 为 1， 则 
表示 这 个 请 求 的 啊 应 头 部 已 经 发 送 过 了 ， 不 需要 再 向 下 执行 ， 直 接 返 回 NGX_OK 即 可 。 








2) 正式 进入 发 送 啊 应 头 部 阶段 ， 为 防止 反复 地 发 送 啊 应 头 部 ， 将 header sent 标 志 位 置 
为 1。 同 时 需要 检查 当前 请 求 是 否 是 客户 端 发 来 的 原始 请 求 ， 如 果 当 前 请 求 只 是 一 个 子 请 
求 ， 它 是 不 存在 发 送 HITP 响 应 头 部 这 个 概念 的 ， 因 此 ， 如 果 当 前 请 求 不 是 main 成 员 指向 的 
原始 请 求 时 ， 跳 到 第 1 步 直接 返回 NGX_OK。 如 果 HTTP 版 本 小 于 1.0， 同 样 不 需要 发 送 响应 
头 部 ， 仍 然 跳 到 第 1 步 返回 NGX_OK。 





























3) 根据 请 求 headers_out 结 构 体 中 的 错误 码 、HITP 头 部 字符 串 ， 计 算出 如 果 把 响应 头 部 


序列 化 为 一 个 字符 串 共 需要 多 少 字 节 。 











4) 在 请 求 的 内 存 池 中 分 配 第 3 步 计 算出 的 缓冲 区 。 
5) 将 响应 行 、 头 部 按照 HTTP 的 规范 序列 化 地 复制 到 缓冲 区 中 。 


6) 将 第 4 步 中 分 配 的 缓冲 区 作为 参数 调用 ngx http write filter 方法 ， 将 啊 应 头 部 发 送出 
去 。 





注意 ， 第 6 步 是 通过 调用 ngx http_ write _filter 方 法 来 发 送 响应 头 部 的 。 事 实 上 ， 这 个 方法 
是 包 体 过 滤 模 块 链表 中 的 最 后 一 个 模块 ngx http write filter module 的 处 理 方法 ， 当 HTTP 模 
块 调 用 ngx_http_output_filter 方 法 发 送 包 体 时 ， 最 终 也 是 通过 该 方法 发 送 啊 应 的 《在 11.9.2 节 中 
将 详细 地 介绍 这 一 方法 ) 。 当 一 次 无 法 发 送 全 部 的 缓冲 区 内 容 时 ，nsgx http_ write filter 方 法 
是 会 返回 NGX_AGAIN 的 《同时 将 未 发 送 完成 的 缓冲 区 放 到 请 求 的 out 成 员 中 ) ， 也 就 是 说 ， 
发 送 啊 应 头 部 的 ngx http_ header filter 方 法 会 返回 NGX _ AGAIN。 如 果 不 需要 再 发 送 包 体 ， 那 
么 这 时 就 需要 调用 ngx_http_finalize_request 方 法 来 结束 请 求 ， 其 中 第 2 个 参数 务必 要 传递 
NGX_AGAIN， 这 样 HTTP 框 架 才 会 继续 将 可 写 事件 注册 到 epoll， 并 持续 地 把 请 求 的 out 成 员 
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中 缓冲 区 里 的 HTTP 啊 应 发 送 完 毕 才 会 结束 请 求 。 


11.9.2 ngx http output filter 





ngx_http_output filter 方 法 用 于 发 送 啊 应 包 体 ， 它 的 第 2 个 参数 就 是 用 于 存放 啊 应 包 体 的 组 
冲 区 ， 如 下 所 示 。 





ngx int t ngx http write filter(ngx http request t r, ngx chain t in) 











其 中 第 2 个 参数 in 在 第 6 章 中 己 有 过 详细 的 介绍 ， 这 里 不 再 袭 述 。 用 于 过 滤 包 体 的 HTTP 
模块 将 以 ngx_ http_next body filter 作 为 链表 指针 连接 成 一 个 流水 线 ，ngx_http_output filter 方 法 
在 发 送 包 体 时 会 依次 调用 各 个 过 滤 包 体 方法 ， 其 中 最 后 一 个 过 滤 包 体 方 法 就 是 11.9.1 节 中 介 
绍 过 的 ngx_http_write_ filter 方法 ， 它 属于 ngx_ http_ write filter module 模 块 。 








本 市 与 ngx_ http send header 方 法 的 介绍 一 样 ， 不 会 讨论 每 个 过 小 模块 的 功能 ， 我 们 只 看 
最 后 一 个 包 体 过 小 模块 是 怎样 发 送 啊 应 包 体 的 。 在 图 11-20 中 ，ngx_http_write_filter 方 法 展示 
了 HTTP 框 架 是 如 何 开 始 发 送 HTTP 啊 应 包 体 的 。 





图 11-20 中 描述 的 ngx_http_write_filter 方 法 主要 有 13 个 步 又 ， 下 面 详细 介绍 这 些 步 又 到 底 
是 如 何 工作 的 。 


1) 首先 检查 请 求 的 连接 上 ngx_connection t 结 构 体 的 error 标 志 人 位， 如果 error 为 1 表示 请 求 
出 错 ， 那 么 直接 返回 NGX_ERROR。 


2) 找到 请 求 的 ngx_http_ request t 结 构 体 中 存放 的 等 待 发 送 的 绥 冲 区 链表 out， 退 历 这 个 
ngx_chain t 类 型 的 绥 冲 区 链表 ， 计 算出 out 绥 冲 区 共 占 用 了 多 大 的 字 节 数 ， 为 第 9 步 发 送 响 应 
做 准备 。 

@ 注意 这 个 out 链 表 通 常 都 保存 着 待 发 送 的 响应 。 ， 在 调用 ngx_http_send_header 
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方法 时 ， 如 果 HTTP 响 应 头 部 过 大 导致 无 法 一 次 性 发 送 完 ， 那 么 剩余 的 响应 头 部 就 会 在 out 链 
表 中 。 
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[检查 ngx_connection_ t+ 结构 体 中 的 error 标 志 位 ] 
[error 标 志 位 为 ] 


[error 标 志 位 为 0] 1 ) 返 回 
NGX FRROR 


2) 遍 历 out 绥 冲 区 . 计算 










剩余 响应 长 度 
3) 将 本 次 待 发 送 的 缓冲 区 添加 到 


out 尾 部 并 计算 总 长 度 
[检测 现在 的 out 缓 冲 区 是 否 完 整 ,是否 有 必要 现在 就 发 送 ] 
[out 不 完整 ， 本 次 可 不 发 送 ] 


[out 缓冲 区 完整 ] 


4) 取 出 配置 项 sendfile_max_chunk 





并 检查 它 是 否 大 于 out 啊 应 长 度 


[检查 写 事 件 delayed 标 志 位 , 以 及 请 求 的 limit_rate 标 志 位 ] 









0, 需要 限 速 ] 


[limit_rate 不 
[limit_rate 为 0] 











6) 计算 发 送 速度 是 否 


2 [delayed 为 1， 当 前 不 得 发 送 啊 应 ] 
超过 了 限制 


[目前 发 送 响应 的 速度 过 快 需要 减速 ] 
[ 不 需 \ 希 台 到 减速 ] 


7) 写 事 件 的 delayed 





9) 向 客 广 端 健 送 缓冲 区 标志 位 置 为 1 
守 流 


[再 次 检查 limlt_rate 标 志 位 ] 
8) 将 写 事件 加 入 





定时 再 


[limit_rate 不 为 0, 需要 限 速 ] 







[limit_rate 为 0] 










10) 再 次 计算 发 送 速度 
是 否 超 讨 限制 


[不 需要 减速 ] 


A 5 ) 将 buffer 标 志 位 置 为 可 写 状态 ， 
[发 送 啊 应 速度 过 快 需 要 减速 | 并 返回 NGX ACAIN 





11) 将 写 事件 添加 到 
定时 : [还 有 剩余 缓冲 区 竺 发送 ] 





V/ 
12) 重 置 out 绥 冲 区 .， 
释放 已 经 发 送 的 缓存 
[检查 啊 应 是 否 全 部 发 送 完毕 ] 


本 到 部 [发 送 完毕 ] 
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图 11-20 ”ngx_http_write_filtet 方 法 的 流程 图 





3) ngx_http_ write filter 方法 的 第 2 个 参数 ip 就 是 本 次 要 发 送 的 缓冲 区 链表 《〈 正 是 由 HITP 
模块 构造 、 传 递 ) ， 本 步 又 将 类 似 第 2 步 通 历 这 个 ngx_chain t 类 型 的 绥 存 链表 in， 将 in 中 的 组 
证 区 加 入 到 out 链 表 的 末尾 ， 并 计算 out 绥 冲 区 共 占 用 多 大 的 字 节 数 ， 为 第 9 步 发 送 啊 应 做 准 
备 。 








在 第 >、 第 3 步 的 过 历 过 程 中 ， 会 检查 绥 冲 区 中 每 个 ngx_buf t 苇 的 3 个 标志 位 : flush、 
recycled、last buf， 如 果 这 3 个 标志 位 同时 为 0( 即 待 发 送 的 out 链 表 中 没有 一 个 缓冲 区 表示 响 
应 已 经 结束 或 需要 立刻 发 送出 去 ) ， 而 且 本 次 要 发 送 的 缓冲 区 训 虽 然 不 为 空 ， 但 以 上 两 步 又 
中 计算 出 的 待 发 送 响应 的 大 小 又 小 于 配置 文件 中 的 postpone_output 参 数 ， 那 么 说 明 当 前 的 组 
冲 区 是 不 完整 的 且 没 有 必要 立刻 发 送 ， 于 是 跳 到 第 13 步 直接 返回 NGX_OK。 











4) 取出 nginx.conf 文 件 中 匹配 请 求 的 sendfile max chunk 配 置 项 (如 它 属于 某 个 location 块 
下 的 配置 项 ) ， 为 第 9 步 计算 发 送 啊 应 的 速度 做 准备 。 





首先 检查 连接 上 写 事件 的 标志 位 delayed， 如 果 delayed 为 1， 则 表示 这 一 次 的 epoll 调 度 中 
请 求 仍 需要 减速 ， 是 不 可 以 发 送 响应 的 ，delayed 为 1 指明 了 响应 需要 延迟 发 送 ， 这 时 跳 到 第 5 
步 执行 ， 如 果 delayed 为 0， 表 示 本 次 不 需要 减速 ， 那 么 再 检查 ngx_http_request t 结 构 体 中 的 
limit rate 发 送 响应 的 速率 ， 如 果 1limit rate 为 0， 表 示 这 个 请 求 不 需要 限制 发 送 速度 ， 直 接 跳 
到 第 9 步 执行 ， 如 果 limit_ rate 大 于 0， 则 说 明 发 送 响应 的 速度 不 能 超过 limit rate 指 定 的 速度 ， 
这 时 跳 到 第 6 步 执行 。 


5) 将 客户 端 对 应 的 ngx_connection ft 结构 体 中 的 buffered 标 志 位 放 上 
NGX HTTP_WRITE BUFFERED 宏 ， 同 时 返回 NGX _ AGAIN， 这 是 在 告诉 HTTP 框 架 out 缓 冲 
区 中 还 有 啊 应 等 待 发 送 。 
6) ngx_http_request t 结 构 体 中 的 limit_rate 成 员 表示 发 送 响 应 的 最 大 速率 ， 当 它 大 于 0 
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时 ， 表 示 需 要 限 速 ， 首 先 需要 计算 当前 请 求 的 发 送 速度 是 否 已 经 达到 限 速 条 件 。 





这 里 需要 解释 第 2 章 中 介绍 过 的 nginx.conf 文 件 里 的 两 个 配置 项 : limit rate 和 
limit rate_after。limit rate 表 示 每 秒 可 以 发 送 的 字 节 数 ， 超 过 这 个 数字 就 需要 限 速 ; 然而 ， 限 
速 这 个 动作 必须 是 在 发 送 了 limit rate_after 字 节 的 响应 后 才能 生效 《对 于 小 响应 包 的 优化 设 
计 ) 。 下 面 看 看 这 一 步 是 如 何 使 用 这 两 个 配置 项 来 计算 限 速 的 ， 如 下 所 示 。 


limit = r->limit rate * (ngx time() - r->start sec + 1) 
= (ce->sent: =GLcf=>1imit rate after); 


第 9 章 已 介绍 过 ngx_time() 方 法 ， 它 取出 了 当前 时 间 ， 而 start_sec 表 示 开 始 接收 到 客户 端 
请 求 内 容 的 时 间 ，c->sent 表 示 这 条 连接 上 已 经 发 送 了 的 HTTP 响 应 长 度 ， 这 样 计 算出 的 变量 
limit 就 表示 本 次 可 以 发 送 的 字 节 数 了 。 如 果 1limit 小 于 或 等 于 0， 它 表示 这 个 连接 上 的 发 送 响 
应 速度 已 经 超出 了 limit rate 配 置 项 的 限制 ， 所 以 本 次 不 可 以 继续 发 送 ， 跳 到 第 7 步 执行 ， 如 
果 1limit 大 于 0， 表 示 本 次 可 以 发 送 limit 字 节 的 响应 ， 那 么 跳 到 第 9 步 开始 发 送 响应 。 


7) 由 于 达到 发 送 啊 应 的 速度 上 限 ， 这 时 将 连接 上 写 事件 的 delayed 标 志 位 置 为 1。 


8) 将 写 事件 加 入 定时 器 中 ， 其 中 超时 时 间 要 根据 第 7 步 算出 的 limit 来 计算 ， 如 下 所 示 ; 





ngx adqdqd timer (c->write, (ngx msec t) (- limit * 1000 / r->limit rate + 1)); 


limit 是 已 经 超 发 的 字 节 数 ， 它 是 0 或 者 负数 。 这 个 定时 器 的 超时 时 间 是 超 发 字 节 数 按照 
limit rate 速 率 算 出 需要 等 待 的 时 间 再 加 上 1 坚 秒 ， 它 可 以 使 Nginx 定 时 器 准确 地 在 允许 发 送 啊 
应 时 激活 请 求 。 之 后 转 到 第 5 步 执 行 。 





9) 本 步 将 把 响应 发 送 给 客户 端 。 然 而 ， 缓 冲 区 中 的 响应 可 能 非常 大 ， 那 么 这 一 次 应 该 
发 送 多 少 字 节 呢 ? 这 要 根据 第 6 步 计算 出 的 limit 变 量 ， 以 及 第 4 步 取 得 的 配置 项 
sendfile max_chunk 来 计算 ， 同 时 要 根据 第 2、 第 3 步 遍 历 缓冲 区 计算 出 的 待 发 送 字 节 数 来 决 
定 ， 这 3 个 值 中 的 最 小 值 即 作为 本 次 发 送 的 响应 长 度 。 
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发 送 响应 后 再 次 检查 请 求 的 limit rate 标 志 人 位， 如果 limit rate 为 0， 则 表示 不 需要 限 速 ， 
跳 到 第 12 步 执行 ， 如 果 limit rate 大 于 0， 则 表示 需要 限 速 ， 跳 到 第 10 步 执行 。 








10) 再 次 按照 第 6 步 中 的 方法 计算 刚 发 送 了 部 分 响应 后 ， 请 求 的 发 送 速率 是 否 达到 
limit rate 上限， 如 果 不 需 要 减速 就 直接 跳 到 第 12 步 ， 否 则 继续 执行 第 11 步 。 








11〉 这 时 表示 第 9 步 发 送 的 响应 速度 还 是 过 快 了 ， 己 经 超 发 了 一 些 啊 应 ， 那 么 这 里 类 似 
第 8 步 ， 计 算出 至 少 要 经 过 多 少 坚 秒 后 才 可 以 继续 发 送 ， 调 用 ngx add timer 方 法 将 写 事件 按 
照 上 面 计算 出 的 毫秒 作为 超时 时 间 添 加 到 定时 器 中 。 同 时 ， 把 写 事 件 的 delayed 标 志 位 置 为 
Fs 








12) 重 置 ngx http request t 结 构 体 的 out 绥 冲 区 ， 把 已 经 发 送 成 功 的 缓冲 区 归还 给 内 存 
池 。 如 果 out 链 表 中 还 有 剩余 的 没有 发 送出 去 的 绥 冲 区 ， 则 添加 到 out 链 表 头 部 ， 跳 到 第 5 步 执 
行 ， 如 果 已 经 将 out 链 表 中 的 所 有 缓冲 区 都 发 送 给 客户 端 了 ， 则 执行 第 13 步 。 


13) 返回 NGX_OK 表 示 成 功 。 





以 上 较为 详尽 地 描述 了 负责 实际 发 送 啊 应 的 ngx http write filter 方法 是 怎样 工作 的 ， 包 
括 如 何 更 新 请 求 里 的 out 绥 冲 区 ， 如 何 根据 限 速 条 件 以 及 配置 文件 中 的 sendfile_ max chunk 参 
数 决 定 一 次 可 以 发 送 多 少 字 节 的 啊 应 。 








ngx http send header 方 法 最 终 会 调用 ngx http write filter 方 法 来 发 送 响 应 头 部 ， 而 
ngx http output filter 方 法 最 终 也 是 调用 ngx http write filter 方 法 来 发 送 响 应 包 体 的 ， 同 样 ， 
ngx_http output filter 也 有 可 能 得 到 返回 值 NGX AGAIN (图 11-20 的 第 5 步 ) ， 它 表示 还 有 未 发 
送 的 响应 缓冲 区 在 out 成 员 中 。 这 时 ， 需 要 以 NGX_AGAIN 作 为 参数 调用 
ngx_http_finalize _ request 方法 ， 该 方法 将 把 写 事件 的 回调 方法 设 为 ngx_ http writer 方法， 并 由 
它 来 把 剩 下 的 响应 全 部 发 送 给 客户 端 。 





11.9.3 ngx http writer 
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本 节 介 绍 的 ngx_http_writer 方 法 对 各 个 HTTP 模 块 而 言 是 不 可 见 的 ， 但 实际 上 它 非常 重 
要 ， 因 为 无 论 是 ngx_http_send header 还 是 ngx_http_output _ filter 方法， 它们 在 调用 时 一 般 都 无 
法 发 送 全 部 的 响应 ， 剩 下 的 响应 内 容 都 得 靠 ngx http_ writer 方 法 来 发 送 。 如 何 把 
ngx_http_ writer 方 法 设置 为 请 求 写 事件 的 回调 方法 呢 ? 这 部 分 内 容 将 在 11.10.6 节 中 介绍 ， 此 
处 关注 的 重点 是 ngx_http_ writer 方 法 在 后 台 完 竟 做 了 些 人 什么。 图 11-21 是 ngx_http_ writer 方 法 的 
流程 图 ， 如 果 这 个 请 求 的 连接 上 可 写 事件 被 甬 发 ， 也 就 是 TCP 的 滑动 窗口 在 告诉 Nginx 进 程 可 
以 发 送 响应 了 ， 这 时 ngx_ http writer 方法 就 开始 工作 了 。 
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[检查 写 事件 的 timedout 标记 位 , 确定 发 送 啊 应 是 否 超时 ] 





[timedout 为 1, 写 事件 超时 , 再 检查 写 事 件 的 delayed 标志 位 ] 


[timedout 为 0, 写 事件 未 超时 ] 叶 
[delayed 为 1, 这 里 的 超时 是 由 请 求 限 速 导 致 ] 


[delayed 为 0 请 求 没 有 限 速 ,所 以 这 里 是 真实 的 发 送 响应 超时 ] 










2 ) 置 写 事件 的 timedout、 





1 ) 结束 请 求 并 返回 


delayed 标志 位 为 0 
[检查 写 事件 的 ready 标 志 位 ] 





408 啊 应 码 





[ready 为 0] 
. (3 ) 将 写 事件 加 入 定时 器 中 


[ready 为 1, 连接 上 可 以 发 送 TCP 流 ] 


5 ) 调用 ngx_http_output_filter 
方法 发 送 啊 应 
[检查 发 送 啊 应 后 的 ngx_http_request.t 结构 体 状 态 ] 

[out 缓 冲 区 中 仍 有 未 发 送 的 啊 应 ] 





4) 将 写 事件 加 入 到 epoll 








[out 缓 冲 区 中 的 啊 应 全 部 发 送 完 毕 ] 





6 ) 重 置 write_event_handle! 方 法 





7) 调用 ngx_http_finalize _request 





方法 结束 请 求 


® 


图 11-21 ngx_http_wtitet 方 法 的 流程 图 
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下 面 将 详细 介绍 图 11-21 中 的 7 个 步骤 。 


1) 首先 检查 连接 上 写 事件 的 timedout 标 志 位 ， 如 果 timedout 为 0， 则 表示 写 事件 未 超时 ， 
跳 到 第 5 步 执 行 ， 如 果 timedout 为 1， 则 表示 当前 的 写 事 件 已 经 超时 ， 这 时 有 两 种 可 能 性 : 第 
一 种 ， 由 于 网 络 异 常 或 者 客户 端 长 时 间 不 接收 响应 ， 导 致 真实 的 发 送 响应 超时 ， 第 二 种 ， 由 
于 上 一 次 发 送 响应 时 发 送 速率 过 快 ， 超 过 了 请 求 的 limit rate 速 率 上 限 ， 而 上 节 的 
ngx_http_write filter 方法 就 会 设置 一 个 超时 时 间 将 写 事件 添加 到 定时 器 中 ， 这 时 本 次 的 超时 

只 是 由 限 速 导致 ， 并 非 真 正 超时 〔〈 结 合 图 11-20 理 解 ) 。 那 么 ， 如 何 判断 这 个 超时 是 真 的 超 
时 还 是 出 于 限 速 的 考虑 呢 ? 这 要 看 事件 的 delayed 标 志 位 。 从 图 11-20 中 可 以 看 出 ， 如 果 是 限 
速 把 写 事件 加 入 定时 器 ， 一 定 会 把 delayed 标 志 位 置 为 1， 如 其 中 的 第 7 步 和 第 11 步 。 如 果 写 事 
件 的 delayed 标 志 位 为 0， 那 就 是 真 的 超时 了 ， 这 时 调用 ngx_ http_finalize_ request 方法 结束 请 
求 ， 传 入 的 参数 是 NGX HTTP REQUEST _ TIME OUT， 表 示 需 要 向 客户 端 发 送 408 错 误 码 ; 
如 果 delayed 标 志 位 为 1， 则 继续 执行 第 2 步 。 




















2) 既然 当前 事件 的 超时 是 由 限 速 引起 的 ， 那 么 此 时 可 以 把 写 事件 的 timedout 标 志 位 和 
delayed 标 志 位 都 重 置 为 0。 








再 检查 写 事 件 的 ready 标 志 位 ， 如 果 为 1， 则 表示 在 与 客户 端的 TCP 连 接 上 可 以 及 送 数 
据 ， 跳 到 第 5 步 执 行 ， 如 果 为 0， 则 表示 暂 不 可 发 送 数据 ， 跳 到 第 3 步 执行 。 





3) 将 写 事件 添加 到 定时 器 中 ， 这 里 的 超时 时 间 就 是 配置 文件 中 的 send timeout 人 参数， 与 
限 速 功能 无 关 。 


4) 调用 ngx_ handle_ write_event 方 法 将 写 事件 添加 到 epoll 等 事件 收集 右 中 ， 同 时 
ngx http writer 方 法 结束 。 








5) 调用 ngx_http_output_filter 方 法 及 送 啊 应 ， 其 中 第 2 个 参数 (也 束 是 表示 需要 友 送 的 组 
冲 区 )〉 为 NULL 指 针 。 这 意味 看 ， 需 要 调用 各 包 体 过 滤 模 块 处 理 out 绥 冲 区 中 的 剩余 内 容 ， 最 


pr 





发 送 啊 应 后 ， 碍 看 ngx_http_ request 结构 体 中 的 buffered 和 postponed 标 志 位 ， 如 果 任 一 个 
不 为 0， 则 意味 着 没有 发 送 完 out 中 的 全 部 啊 应 ， 这 时 路 到 第 3 步 执行 ， 请 求 main 指 针 指 加 请 求 
目 身 ， 表 示 这 个 请 求 是 原始 请 求 ， 再 检查 与 客户 端 间 的 连接 ngx_connection t 结 构 体 中 的 
buffered 标 志 位 ， 如 末 buffered 不 为 0%， 同 样 表 示 没 有 发 送 完 out 中 的 全 部 啊 应 ， 仍 然 跳 到 第 3 步 
执行 ， 除 此 以 外 ， 都 表示 out 中 的 全 部 啊 应 皆 发 送 完毕 ， 跳 到 第 6 步 执行 。 








6) 将 请 求 的 write event handler 方 法 置 为 ngx http request_ empty handler， 也 就 是 说 ， 如 
果 这 个 请 求 的 连接 上 再 有 可 写 事件 ， 将 不 做 任何 处 理 。 








7) 调用 ngx http finalize request 方 法 结束 请 求 ， 其 中 第 2 个 参数 传 入 的 是 


ngx http output filter 方 法 的 返回 值 。 


@ 注意。 nex_http_wrfitet 方 法 仅 用 于 在 后 台 发 送 响应 到 客户 端 。 
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11.10 结束 HTTP 请 求 





对 于 事件 驱动 的 架构 来 说 ， 结 束 请 求 是 一 项 复杂 的 工作 。 因 为 一 个 请 求 可 能 会 被 许多 个 
事件 触 友 ， 这 使 得 Nginx 框 架 调 度 到 茶 个 请 求 的 回调 方法 时 ， 在 当前 业务 内 似乎 需要 结 
HTTP 请 求 ， 但 如 果真 的 结束 了 请 求 ， 销 毁 了 与 请 求 相关 的 内 存 ， 多 半 会 造成 重大 错误 ， 
为 这 个 请 求 可 能 还 有 其 他 事件 在 定时 器 或 者 epoll 中 。 当 这 些 事件 被 回调 时 ， 请 求 却 已 经 不 存 
在 了 ， 这 就 是 严重 的 内 存 访问 越界 错误 ! 如 果 答 试 在 属于 茶 个 HTTP 模块 的 回调 方法 中 试图 
结束 请 求 ， 先 要 把 这 个 请 求 相关 的 所 有 事件 (有些 事件 可 能 属于 其 他 HTTP 模 块 ) 都 从 定时 
器 和 epoll 中 取出 并 调用 其 handler 方 法 ， 这 又 太 复杂 了 ， 忆 外 ， 不同 HTTP 模块 上 的 代码 精 合 
大 紧密 将 会 难以 维护 。 

















那 HITP 框 架 又 是 怎样 解决 这 个 问题 的 呢 ? HTTP 框架 把 一 个 请 求 分 为 多 种 动作 ， 如 果 
HTTP 框 架 提 供 的 方法 会 导致 Nginx 再 次 调度 到 请 求 〈 例 如 ， 在 这 个 方法 中 产生 了 新 的 事件 ， 
或 者 重新 将 已 有 事件 添加 到 epoll 或 者 定时 器 中 ) ， 那 么 可 以 认为 这 一 步调 用 是 一 种 独立 的 动 
作 。 例 如 ， 接 收 HTTP 请 求 的 包 体 、 调 用 upstream 机 制 提 供 的 方法 访问 第 三 方 服务 、 派 生出 
subrequest 子 请 求 等 。 这 些 所 谓 独 立 的 动作 ， 部 是 在 告诉 Nginx， 如 果 机 会 合适 束 再 次 调用 它 
们 处 理 请 求 ， 因 为 这 个 动作 并 不 是 Nginx 调 用 一 次 它们 的 方法 束 可 以 处 理 完毕 的 。 因 此 ， 
一 种 动作 对 于 整个 请 求 来 说 都 是 独立 的 ，HTTP 框 架 希望 每 个 动作 结束 时 仅 维 护 自己 的 业 
务 ， 不 用 去 关心 这 个 请 求 是 否 还 做 了 其 他 动作 。 这 种 设计 大 大 降低 了 复杂 上 度 。 





这 种 设计 具体 又 是 怎么 实现 的 呢 ? 实际 上 ， 在 11.8 节 中 已 经 介绍 过 ， 每 个 HTTP 请 求 都 有 
一 个 引用 计数 ， 每 派生 出 一 种 新 的 会 独立 向 事件 收集 器 注册 事件 的 动作 时 如 
ngx http read client request body 方 法 或 者 ngx_http subrequest 方 法 ) ， 都 会 把 引用 计数 加 1， 
这 样 每 个 动作 结束 时 都 通过 调用 ngx http finalize request 方 法 来 结束 请 求 ， 而 
ngx_http_finalize_request 方 法 实际 上 却 会 在 引用 计数 减 1 后 先 检查 引用 计数 的 值 ， 如 果 不 为 0 是 


不 会 真正 销毁 请 求 的 。 
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也 就 是 说 ，HTTP 框 架 要 求 在 请 求 的 某 个 动作 结束 时 ， 必 须 调 用 ngx_http_finalize_ request 
方法 来 结束 请 求 。ngx_http finalize request 方 法 也 设计 得 比较 复杂 ， 在 第 3 章 中 曾经 谈 到 过 它 
最 基本 的 用 法 ， 本 节 中 将 详细 讨论 ngx http finalize request 方 法 到 底 做 了 些 什么 。 


在 说 明 ngx http finalize_ request 方法 前 ， 先 介绍 一 下 HTTP 框 架 提 供 的 几 个 更 低级 别 的 结 
束 请 求 方法 。 


11.10.1 ngx http close connection 
ngx_http_close_connection 方 法 是 HTTP 框 架 提 供 的 一 个 用 于 释放 TCP 连 接 的 方法 ， 它 的 目 


的 很 简单 ， 就 是 关闭 这 个 TCP 连 接 ， 当 且 仪 当 HTTP 请 求 真 正 结束 时 才 会 调用 这 个 方法 。 图 
11-22 列 出 了 ngx http close connection 方 法 所 做 的 工作 。 
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1 ) 将 连接 的 读 / 写 事件 
从 定时 各 中 取出 


2) 将 连接 的 读 / 写 事件 从 
epoll! | 取出 


3) 将 描述 连接 的 nex_connection 1 
结构 体 释 放 到 空闲 连接 池 


4) 关闭 TCP 
连接 


pale EL “A 十 * 
5 ) 杀 毁 连接 nsgx_connection 


中 的 内 存 池 





9 


图 11-22 ngx_http_close_connection 方 法 的 流程 图 
下 面 先 来 分 析 一 下 这 个 底层 的 方法 ngx http close_connection 究 竟 做 了 些 什么 。 


1) 首先 将 连接 的 读 / 写 事件 从 定时 器 中 取出 。 实 际 上 就 是 检查 读 / 写 事件 的 tme_set 标 志 
位 ， 如 果 为 1， 则 证 明 事 件 在 定时 器 中 ， 那 么 需要 调用 ngx_del_timer 方 法 把 事件 从 定时 器 中 移 


除 。 
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2) 调用 ngx del conn 宏 (或 者 ngx del event 宏 ) 将 读 / 写 事件 从 epoll 中 移 除 。 实 际 上 就是 
调用 第 9 章 重 点 介绍 过 的 ngx event actions t 接 口中 的 del_conn 方 法 ， 当 事件 模块 是 epoll 模 块 
时 ， 就 是 从 epoll 中 移 除 这 个 连接 的 读 / 写 事件 。 同 时 ， 如 果 这 个 事件 在 
ngx_posted_accept events 或 者 ngx_ posted_events 队 列 中 ， 还 需要 调用 ngx_delete posted_event 安 
把 事件 从 post 事 件 队列 中 移 除 。 


3) 调用 ngx_free_connection 方 法 把 表示 连接 的 ngx_connection t 结 构 体 归还 给 ngx_cycle_t 
核心 结构 体 的 空闲 连接 池 free_connections。 


4) 调用 系统 提供 的 close 方 法 关闭 这 个 TCP 连 接 套 接 字 。 

5) 销毁 ngx_connection t 结 构 体 中 的 pool 内 存 池 。 

可 见 ， 这 个 ngx http_close_connection 方 法 主要 是 针对 连接 做 了 一 些 工 作 ， 它 是 非常 基础 
网 困 用 


11.10.2 ngx http free request 


ngx_http_free_request 方 法 将 会 释放 请 求 对 应 的 ngx_http_request 堵 据 结构 ， 它 并 不 会 像 
ngx_http_close_connection 方 法 一 样 去 释放 承载 请 求 的 TCP 连 接 ， 每 一 个 TCP 连 接 可 以 反复 地 
承载 多 个 HTTP 请 求 ， 因 此 ，ngx http free request 是 比 ngx http close connection 更 高 层次 的 方 
法 ， 前 者 必然 先 于 后 者 调用 。 下 面 看 看 图 11-23 中 ngx http free request 方 法 到 底 做 了 哪些 工 
作 % 


在 描述 图 11-23 之 前 ， 先 来 看 一 个 数据 结构 ngx http_cleanup t， 它 的 定义 如 下 。 
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] ) 调用 请 求 cleanup 
链表 内 的 方法 做 清理 工作 







2 ) 调用 NGX_HTTP LOG_PHASE 
阶段 的 回调 方法 记录 日 志 












3 ) 销毁 请 求 ngx_htth_request_t 
中 的 内 存 池 





图 11-23 negx_http_free_request 方 法 的 流程 图 





typedef struct ngx http cleanup s ngx http cleanup t; 
struct ngx http cleanup s { 
// 由 


HTTP 模 块 提供 的 清理 资源 的 回调 方法 


ngx http cleanup pt handler; 
// 和 希望 给 上 面 的 


handler 方 法 传递 的 参数 


void data; 
/一 个 请 求 可 能 会 有 多 个 


ngx_http cleanup 清理 方法 ， 这 些 清理 方法 间 就 是 通过 


next 指 针 连 接 成 单 链表 的 
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/ 
ngx http cleanup t next; 
}; 





事实 上 ， 任 何 一 个 请 求 的 ngx_http_request t 结 构 体 中 都 有 一 个 ngx_http_cleanup {类 型 的 成 
员 cleanup， 如 果 没 有 需要 清理 的 资源 ， 则 cleanup 为 空 指针 ， 否 则 HTTP 模 块 可 以 向 cleanup 中 
以 单 链表 的 形式 无 限制 地 添加 ngx_http_cleanup t 结 构 体 ， 用 以 在 请 求 结 束 时 释放 资源 。 再 看 
看 handler 方 法 的 定义 ， 如 下 所 示 。 











typedef void (*ngx http cleanup pt) (void *data); 








如 果 需 要 在 请 求 释放 时 执行 一 些 回 调 方法 ， 首 先 需 要 实现 一 个 ngx_http_cleanup_pt 方 法 。 
当然 ，HTTP 框 架 还 很 友好 地 提供 了 一 个 工具 方法 ngx http_cleanup _ add， 用 于 回 请 求 中 添加 
ngx_http_cleanup_t 结 构 体 ， 其 定义 如 下 。 








ngx http cleanup t * ngx http cleanup add(ngx http request t *r, size t size) 








这 个 方法 返回 的 就 是 已 经 插入 请 求 的 ngx http_cleanup t 结 构 体 指针 ， 其 中 data 成 员 指 向 
的 内 存 都 已 经 分 配 好 ， 内 存 的 大 小 由 size 参 数 指定 。 





@ 注意 事实 上 ， 在 3.8.2 节 中 曾经 简单 地 介绍 过 同样 用 于 清理 资源 的 
nex_pool_cleanup_t， 它 与 ngx_http_cleanup_pt 是 不 同 的 ，ngx_pool_cleanup_t 仅 在 所 用 的 内 存 池 
销毁 时 才 会 被 调用 来 清理 资源 ， 它 何 时 释放 资源 将 视 所 使 用 的 内 存 池 而 定 ， 而 


ngx_http_cleanup_pt 是 在 nex_http_request_t 结 构 体 释放 时 被 调用 来 释放 资源 的 。 
下 面 说 明 一 下 ngx http free request 方 法 所 做 的 3 项 主要 工作 。 


1) 循环 地 避 历 请 求 ngx_http_request t 结 构 体 中 的 cleanup 链 表 ， 依 次 调用 每 一 个 
ngx_http_cleanup_pt 方 法 释放 资源 。 


2) 在 11 个 ngx_http_phases 阶 段 中 ， 最 后 一 个 阶段 叫做 NGX_HTTP_LOG PHASE， 它 是 用 
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来 记录 客户 端的 访问 日 志 的 。 在 这 一 步骤 中 ， 将 会 依次 调用 NGX_HTTP_LOG _ PHASE 阶段 的 
所 有 回调 方法 记录 日 志 。 官 方 的 ngx_http log module 模 块 就 是 在 这 里 记录 access log 的 。 








3) 销毁 请 求 ngx_http_request t 绪 构 体 中 的 pool 内 存 池 。 在 销毁 内 存 池 时 ， 挂 在 该 内 存 池 
下 的 由 各 Nginx 模 块 实现 的 ngx pool cleanup {方法 也 会 被 调用 ， 注 意 它 与 第 1 步 的 区 别 。 


er 注意 ”如 果 打 开 了 统计 HTTP 请 求 的 功能 ，ngx_http_free_request 方 法 还 会 更 新 共享 内 


存 中 的 统计 请 求 数量 的 两 个 原子 变量 : ngx_stat_reading、ngx_stat_writing， 详 见 14.2.1 节 。 


11.10.3 ngx http _ close request 








ngx_http_close_request 方 法 是 更 高 层 的 用 于 关闭 请 求 的 方法 ， 当 然 ，HTTP 模 块 一 般 也 不 
会 直接 调用 它 的 。 在 上 面 几 节 中 反复 提 到 的 引用 计数 ， 就 是 由 ngx_http_close_request 方 法 负 
责 检测 的 ， 同 时 它 会 在 引用 计数 清 零 时 正式 调用 ngx_http free_request 方 法 和 
ngx_http_close_connection 方 法 来 释放 请 求 、 关 闭 连 接 。 先 来 看 看 图 11-24 中 列 出 的 
ngx_http_close request 方 法 所 做 的 工作 。 
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1 ) 对 应 的 原始 请 求 的 
引用 计数 减 ] 
| 伶 查 厚 始 请 求 的 count51 用 i 上 数值 和 了 block 标志 位 | 











[count 等 于 0 日 blocked 为 01 


2 调用 ngx_http_free _request 方 法 





| count 大 于 0 或 者 block 大 于 0 | 


3 ) 调用 ngx_http_close_connection 方 法 


图 11-24 ngx_http_close_request 方 法 的 流程 图 
下 面 简单 说 明 一 下 ngx_http_close_ request 方法 所 做 的 工作 。 


1) 首先 ， 由 ngx_http_ request t 结 构 体 的 main 成 员 中 取出 对 应 的 原始 请 求 (当然 ， 可 能 束 
是 这 个 请 求 本 映 ) ， 再 取出 count 引 用 计数 并 减 1。 然 后 ， 检 查 count 引 用 计数 是 否 已 经 为 0， 
以 及 blocked 标 志 位 是 否 为 0。 如 果 count 已 经 为 0， 则 证 明 请 求 没有 其 他 动作 要 使 用 了 ， 同 时 
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blocked 标 志 位 也 为 0%， 表 示 没 有 HTTP 模 块 还 需要 处 理 请 求 ， 所 以 此 时 请 求 可 以 真正 释放 ， 这 
时 跳 到 第 2 步 执 行 ， 如 果 count 引 用 计数 大 于 0， 或 者 blocked 大 于 0， 这 样 都 不 可 以 结束 请 求 ， 
ngx http close request 方 法 直接 结 


2) 调用 ngx http free request 方 法 释放 请 求 。 
3) 调用 ngx http_close_connection 方 法 关闭 连接 。 


G 注意 ”在 官方 发 布 的 HTTP 模 块 中 ，ngx_http_request_t 结 构 体 中 的 blocked 标 志 位 主要 
由 异步 1/ 〇 使 用 ，ngx_http_close_request 方 法 正 是 通过 blocked 配 合 着 异步 1/O 工 作 ， 如 果 AIO 
上 下 文中 还 在 处 理 这 个 请 求 ，blocked 必 然 是 大 于 0 的 ， 这 时 ngx_http_close_request 方 法 不 能 结 


束 请 求 。 由 于 本 章 不 涉及 异步 IO ， 所 以 略 过 不 提 。 
11.10.4 ngx http finalize connection 


ngx http finalize connection 方 法 虽然 比 ngx http_close request 方 法 高 了 一 个 层次 ， 但 
HTTP 模 块 一 般 还 是 不 会 直接 调用 它 。ngx http finalize connection 方 法 在 结束 请 求 时 ， 解 决 了 
keepalive 特 性 和 子 请 求 的 问题 ， 图 11-25 中 展示 了 它 所 做 的 工作 。 





下 面 简单 分 析 一 下 ngx_http finalize connection 方 法 所 做 的 工作 。 














1) 首先 查看 原始 请 求 的 引用 计数 ， 如 果 不 等 于 1， 则 表示 还 有 多 个 动作 在 操作 着 请 求 ， 
接着 继续 检查 discard _ body 标志 位 。 如 果 discard body 为 0， 则 直接 跳 到 第 3 步 ， 如 果 
discard_body 为 1， 则 表示 正在 丢弃 包 体 ， 这 时 会 再 一 次 把 请 求 的 read_event_handler 成 员 设 为 
ngx http_discarded request body handler 方 法 ， 就 如 同 11.8.2 节 中 描述 的 一 样 。 
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S 


[ 检查 原始 请 求 的 count 引 用 计数 ] 





[count 不 等 于 1， 检查 discard_body 标志 位 请 求 是 否 正 丢弃 包 体 | 





[discard_body 为 1] 


1 ) 为 丢弃 包 体 设置 读 [ count 为 1, 检查 keepalive 标志 位 ] 
事件 处 理 方法 





[discard body 为 0] 
2) 将 读 事件 添加 到 
定时 器 中 









[keepalive 为 0, 检查 是 否 需 要 延迟 关闭 请 求 ] 


[不 需要 延迟 关闭 请 求 ] 


3 ) 调 用 ngx_http_close _ request 





方法 结束 请 求 [ keepalive 为 1, 请 求 基于 keep -alive 连 接 ] 


4) 调 用 ngx_http_set_lingering _close 


方法 延迟 关闭 


5 ) 调 用 ngx_http_set_keepalive 
方法 设置 keepalive 连 接 





© 


图 11-25 ”ngx_http_finalize_connection 方 法 的 流程 


如 果 引 用 计数 为 1， 则 说 明 这 时 要 真 的 准备 结束 请 求 了 。 不 过 ， 还 要 检查 请 求 的 
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keepalive 成 员 ， 如 有 果 keepalive 为 1， 则 说 明 这 个 请 求 需要 释放 ， 但 TCP 连 接 还 是 要 复 用 的 ， 
时 跳 到 第 5 步 执 行 ， 如 果 keepalive 为 0 就 不 需要 考虑 keepalive 请 求 了 ， 但 还 需要 检测 请 求 的 
lingering close 成 员 ， 如 果 lingering_close 为 1， 则 说 明 需 要 延迟 关闭 请 求 ， 这 时 也 不 能 真 的 去 
结束 请 求 ， 而 是 跳 到 第 4 步 ， 如 果 lingering close 为 0， 才 真 的 跳 到 第 5 步 结束 请 求 。 





2) 将 读 事件 添加 到 定时 器 中 ， 其 中 超时 时 间 是 lingering timeout 配 置 项 。 
3) 调用 11.10.3 节 介绍 的 ngx http_close request 方 法 结束 请 求 。 


4) 调用 ngx_http_set_lingering close 方法 延迟 关闭 请 求 。 实 际 上 ， 这 个 方法 的 意义 克 在 于 
把 一 些 必须 做 的 事情 做 完 〈 如 接收 用 户 端 发 来 的 字符 流 ) 再 关闭 连接 。 


5) 调用 ngx_http_set_keepalive 方 法 将 当前 连接 设 为 keepalive 状 态 。 它 实际 上 会 把 表示 请 
求 的 ngx http request t 结 构 体 释放 ， 却 又 不 会 调用 ngx http close_connection 方 法 关闭 连接 ， 同 
时 也 在 检测 keepalive 连 接 是 否 超时 ， 对 于 这 个 方法 ， 此 处 不 做 详细 解释 。 





11.10.5 ngx http terminate request 


ngx_http_ terminate request 方 法 是 提供 给 HTTP 模 块 使 用 的 结束 请 求 方法 ， 但 它 属于 非 正 
常 结束 的 场景 ， 可 以 理解 为 强制 关闭 请 求 。 也 就 是 说 ， 当 调用 ngx_http_terminate request 方 法 
结束 请 求 时 ， 它 会 直接 找 出 该 请 求 的 main 成 员 指 向 的 原始 请 求 ， 并 直接 将 该 原始 请 求 的 引用 
计数 置 为 1， 同 时 会 调用 ngx_http_close_request 方 法 去 关闭 请 求 。 与 上 文 不 同 的 是 ， 它 是 
HTTP 框 架 提供 给 各 个 HTTP 模 块 直接 使 用 的 方法 ， 篇 幅 所 限 ， 这 个 方法 就 不 再 详细 介绍 了 。 











11.10.6 ngx http finalize request 





ngx_http_finalize_request 方 法 是 开发 HTTP 模 块 时 最 常 使 用 的 结束 请 求 方法 ， 在 第 3 间 中 早 
己 介 绍 过 它 的 简单 用 法 。 事 实 上 ，ngx http finalize request 方 法 被 HTTP 框 架设 计 得 极为 复 
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杂 ， 各 种 结束 请 求 的 场景 都 被 它 考虑 到 了 ， 下 面 将 详细 讲述 这 个 方法 完 竟 做 了 些 什么 。 首 移 
回顾 一 下 它 的 定义 。 





void ngx http finalize request (ngx http request t *r, ngx int t rc) 











其 中 ， 参 数 r 就 是 当前 请 求 ， 它 可 能 是 派生 出 的 子 请 求 ， 也 可 能 是 客户 端 发 来 的 原始 请 
求 。 后 面 的 参数 rc 就 非常 复杂 了 ， 它 既 可 能 是 NGX_ OK、NGX _ ERROR、NGX _ AGAIN、 
NGX_ DONE、NGX_DECLINED 这 种 系统 定义 的 返回 值 ， 又 可 能 是 类 似 
NGX HTTP REQUEST TIME OUT 这 样 的 HTTP 响 应 码 ， 因 此 ，ngx http finalize request 方法 
的 流程 异常 复杂 。 学 习 如 何 正确 地 使 用 ngx http_finalize request 方 法 非常 关键 ， 因 为 会 涉及 不 
同 动作 导致 的 引用 计数 增加 、 腊 常情 况 下 自动 构造 啊 应 、 未 发 送 完 所 有 响应 时 自动 向 事件 杠 
架 添 加 写 事 件 回 调 方法 ngx_http_writer 等 各 种 场景 。 大 多 数 情况 下 ， 我 们 都 会 把 其 他 Nginx 方 
法 的 返回 值 作为 rc 参数 来 调用 ngx http finalize request 方 法， 但 如 果 要 编写 复杂 的 HITP 模 
块 ， 还 是 需要 清晰 地 认识 ngx http finalize request 方 法 的 工作 原理 。 











下 面 把 ngx_http_finalize_ request 方法 的 主要 流程 简化 为 了 17 个 主要 步 又， 如 网 11-26 所 


小 。 
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1 ) 怕 查 第 2 个 


[rc 参数 为 NGX_DECLINED] 


2 ) 设置 write_event_handler 方 法 为 





,Ore hases 
[re 参数 不 是 NGX_DEGLINED 和 NGX_DONG， 
检查 是 否 为 原始 请 求 ] 

[rc 参数 为 NGX_DONE] 
[属于 subreguest 子 请 求 ] 





[原始 请 求 ] 
5) 调 用 post_subrequest 
的 handler 方 法 4) 调 用 ngx_http finalize_connection 
法 结束 请 求 
6) 再 次 检查 rc 参 性 


[re 人 参数 为 NGX_ERROR，NGX_HTTP_REOUEST_TIME_OUT、 
NGX_HTTP_CLIENT_CLOSED_REOUEST， 或 者 连接 错误 ] 
[re 参数 为 201 或 者 204, 以 及 re 的 值 大 于 或 等 于 300] 









8) 夺 为 原始 请 求 就 由 汉 时 角 中 
去 除 读 / 写 事 
[rc 为 其 他 值 ] 





9 ) 训 年 该 / 事件 的 处 理 方法 为 


_http request handler 











7) 调用 ngx_http_terminate_request 

方法 强制 结束 请 求 

10) 调 用 ngx_http_special_response_handler 
方法 发 送 啊 应 










1D 青 次 调用 ngx http ali _request 
法 结 < 





原 : 始 请 求 
[检查 r 是 否 等 于 r-> main] 
[当前 请 求 不 是 原始 请 求 ] 13) 将 其 区 请 求 深 加 到 





sted_postedrequests 链 表 中 
en posted_postedreques 
[ou 缓冲 区 还 有 剩余 响应 ] 






[out 绥 冲 区 中 的 响 立 者 已 发 送 公 字 毕 ] 
14) 设 置 ngx_http_writer 
16) 由 定时 器 中 移 除 为 写 事 件 回 调 方法 
读 / 写 事件 







15) 将 写 事 件 添加 到 定时 器 


17) 调用 ngx_http_finalize_connection 
方法 结束 请 求 
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图 11-26 ”ngx_http_finalize_request 方 法 的 流程 图 





下 面 解释 一 下 ngx _http finalize request 方 法 所 做 的 工作 。 


1) 首先 检查 rc 参数 。 如 果 rc 为 NGX DECLINED， 则 跳 到 第 2 步 执行 ， 如 果 rc 为 
NGX DONE， 则 跳 到 第 4 步 执行 ， 除 此 之 外 ， 都 继续 执行 第 $ 步 。 


2) NGX_ DECLINED 参 数 表 示 请 求 还 需要 按照 11 个 HTTP 阶 段 继续 处 理 下 去 ， 参 考 11.6 节 
的 内 容 可 以 知道 ， 这 时 需要 继续 调用 ngx http_ core _ run phases 方 法 处 理 请 求 。 这 一 步 中 首先 
会 把 ngx http_ request t 结 构 体 的 write event handler 设 为 ngx http core run phases 方 法 。 同 时 ， 
将 请 求 的 content handler 成 员 置 为 NULL 空 指针 ，11.6 节 已 介绍 过 这 个 成 员 ， 它 是 一 种 用 于 在 
NGX HTTP_CONTENT PHASE 阶 段 处 理 请 求 的 方式 ， 将 其 设置 为 NULL 是 为 了 让 
ngx_http_core_content phase 方 法 (11.6.4 节 介绍 ) 可 以 继续 调用 





NGX HTTP_CONTENT _ PHASE 阶段 的 其 他 处 理 方 法 。 
3) 调用 ngx http core run phases 方 法 继续 处 理 请 求 ，ngx_http finalize _ request 方法 结 


4) NGX_DONE 参 数 表示 不 需要 做 任何 事 ， 直 接 调 用 ngx_http_finalize_connection 方 法 ， 
之 后 ngx_http_finalize_request 方 法 结束 。 当 某 一 种 动作 (如 接收 HTTP 请 求 包 体 〉 正 常 结束 而 
请 求 还 有 业务 要 继续 处 理 时 ， 多 半 都 是 传递 NGX_DONE 参 数 。 由 11.10.4 节 我 们 知道 ， 这 个 
ngx_http_finalize_connection 方 法 还 会 去 检查 引用 计数 情况 ， 并 不 一 定 会 销毁 请 求 。 














5) 检查 当前 请 求 是 否 为 subrequest 子 请 求 ， 如 果 不 是 ， 则 跳 到 第 6 步 执 行 ， 如 果 是 子 请 
求 ， 那 么 调用 post_subrequest 下 的 handler 回 调 方 法 。 在 第 6 章 中 曾经 介绍 过 subrequest 的 用 法 ， 
可 以 看 到 post_subrequest 正 是 此 时 被 调用 的 。 











6) 第 1 步 只 是 把 re 参数 的 两 种 特殊 值 处 理 挥 了 ， 现 在 义 需 要 再 次 检查 rc 参数 了 。 如 果 rc 
值 为 NGX ERROR、NGX HTTP REQUEST TIME OUT、NGX HTTP CLOSE、 
NGX_HTTP_CLIENT_ CLOSED _ REQUEST， 或 者 这 个 连接 的 error 标 志 为 1， 那 么 跳 到 第 7 步 执 
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行 ; 如 果 rc 为 NGX HTTP CREATED、NGX _ HTTP NO_CONTENT 或 者 大 于 或 等 于 

NGX HTTP SPECIAL RESPONSE， 则 表示 请 求 的 动作 是 上 传 文件 ， 或 者 HTTP 模 块 需要 
HTTP 框 架构 造 并 发 送 响应 码 大 于 或 等 于 300 以 上 的 特殊 响应 ， 这 时 跳 到 第 8 步 执 行 ， 其 他 情 
况 下 ， 直 接 跳 到 第 12 步 执行 。 


7) 这 一 步 直接 调用 ngx http terminate request 方 法 强制 结束 请 求 ， 同 时 ， 
ngx http finalize request 方 法 结 








8) 检查 当前 请 求 的 main 是 否 指 问 自己 ， 如 果 是 ， 这 个 请 求 就 是 来 自 客户 端的 原始 请 求 
( 非 子 请 求 ) ， 这 时 检查 读 / 写 事件 的 timer_ set 标志 位 ， 如 果 timer set 为 1， 则 表明 事件 在 定时 
器 中 ， 需 要 调用 ngx del timer 方 法 把 读 / 写 事件 从 定时 器 中 移 除 。 








9) 设置 读 / 写 事件 的 回调 方法 为 ngx http request handler 方 法 ， 这 个 方法 在 11.6 节 中 介绍 
过 ， 它 会 继续 处 理 HTTP 请 求 。 


10) 调用 ngx http special response handler 方 法 ， 该 方法 负责 根据 rc 参数 构造 完整 的 
HTTP 响 应 。 为 什么 可 以 在 这 一 步 中 构造 这 样 的 响应 呢 ? 回顾 一 下 第 7 步 ， 这 时 rc 要 么 是 表示 
上 传 成 功 的 201 或 者 204， 要 么 就 是 表示 异步 的 300 以 上 的 响应 码 ， 对 于 这 些 情况 ， 都 是 可 以 
让 HTTP 框 架 独 立 构造 响应 包 的 。 





11) 再 次 调用 ngx_http_finalize_request 方 法 结束 请 求 ， 不 过 这 时 的 re 参数 实际 上 是 第 10 步 
ngx http_ special response handler 方 法 的 返回 值 。 





12) 再 次 检查 请 求 的 main 成 员 是 否 指向 自己 ， 即 当前 请 求 是 否 为 原始 请 求 。 如 果 不 是 客 
户 端 发 来 的 原始 请 求 ， 跳 到 13 步 继续 执行 ， 如 果 是 原始 请 求 ， 那 么 还 需要 检查 out 缓 冲 区 内 
是 否 还 有 没 发 送 完 的 响应 ， 如 果 有 ， 则 跳 到 第 14 步 继续 执行 ， 如 果 没 有 ， 则 可 以 结束 请 求 
了 ， 此 时 跳 到 第 16 步 。 





13) 由 于 当前 请 求 是 子 请 求 ， 那 么 正常 情况 下 需要 跳 到 它 的 父 请 求 上 ， 激 活 父 请 求 继续 
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向 下 执行 ， 所 以 这 一 步 首 先 根据 ngx _http_ request t 结 构 体 的 parent 成 员 找 到 父 请 求 ， 再 构造 一 
个 ngx_http_posted_request t 结 构 体 把 父 请 求 放置 其 中 ， 最 后 把 该 结构 体 添 加 到 原始 请 求 的 
posted requests 链 表 中 ， 这 样 11.7 节 中 介绍 过 的 ngx _http run posted_requests 方 法 就 会 在 图 11- 
12 描 述 的 流程 中 调用 父 请 求 的 write_event handler 方 法 了 。 








14) 在 11.9 节 中 多 次 讲 到 ， 当 HTTP 响应 过 大 ， 无 法 一 次 性 发 送 给 客户 端 时 ， 需 要 调用 
ngx_http_finalize request 方法 结束 请 求 ， 而 该 方法 会 把 11.9.3 节 介绍 的 ngx_http_writer 方 法 注册 
给 epoll 和 定时 器 ， 当 连接 再 次 可 写 时 就 会 继续 用 送 剩余 的 啊 应 ， 这 些 工 作 就 是 在 第 14、 第 15 
步 中 完成 的 。 这 一 步 先 把 请 求 的 write event handler 成 员 设 为 ngx http writer 方 法。 


15) 如 果 写 事件 的 delayed 标 志 位 为 0， 就 把 写 事件 添加 到 定时 器 中 ， 超 时 时 间 就 是 
nginx.conf 文 件 中 的 send_timeout 配 置 项 ， 当 然 ， 如 果 delayed 为 1， 则 表示 限制 发 送 速 上 度 ， 从 
11.9.2 节 可 以 看 出 ， 在 需要 限 速 时 ， 根 据 计算 得 到 的 超时 时 间 已 经 把 写 事件 添加 到 定时 器 中 
了 。 再 调用 ngx handle write event 方 法 把 写 事 件 添加 到 epoll 中 。 








16) 到 了 这 里 真 的 要 结束 请 求 了 。 首 先 判断 读 / 写 事件 的 timer_set 标 志 位 ， 如 采 timer_set 
为 1， 则 需要 把 相应 的 读 / 写 事件 从 定时 器 中 移 除 。 





17) 调用 11.10.4 节 中 介绍 过 的 ngx_http finalize connection 方 法 结束 请 求 。 


事实 上 ，nsx http finalize request 方 法 的 分 支流 程 远 不 止 上 面 的 17 步 ， 为 了 让 读者 清晰 地 
理解 其 主要 工作 ， 许 多 不 太 重 要 的 分 文 都 从 图 10-26 中 去 除了 。 到 此 ， 读 者 应 当 对 
ngx_http_finalize request 方法 有 了 相当 全 面 的 了 解 ， 这 时 再 开发 HTTP 模块 就 可 以 灵活 地 指定 
rc 参数 了 。 
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11.11 沙 结 





本 章 系 统 地 介绍 了 HTTP 框 架 是 如 何 运 行 的 ， 特 别 是 它 如 何 与 第 9 章 介绍 的 事件 框架 交 
互 ， 以 及 如 何 与 本 书 第 二 部 分 介绍 的 普通 HTTP 模 块 交 互 。 阅 读 完 本 章 内 容 后 ， 相 信 读 者 会 
对 HTTP 模 块 的 开 及 有 一 个 全 新 的 认识 ， 甚 至 对 于 在 HTTP 请 求 的 处 理 过 程 中 HTTP 模块 占 用 
的 服务 器 资源 都 会 有 深入 的 了 解 ， 也 就 是 说 ， 这 时 读者 应 当 具 备 开 发 复杂 的 HTTP 模块 的 能 
力 了 ， 甚 至 可 以 处 理 非 HITP， 而 是 其 他 基于 TCP 的 应 用 层 协 议 ， 它 们 也 可 以 仿照 HTTP 框 
架 ， 定 义 一 种 新 的 模块 类 型 和 处 理 框 架 ， 从 而 高 效 地 处 理 新 业务 。 





upstream 机 制 实际 上 也 属于 HTTP 框 架 的 内 容 ， 下 一 章 中 我 们 将 介绍 它 的 实现 原理 。 
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第 12 间 ”upstream 机 制 的 设计 与 实现 


第 5 章 中 曾经 举例 说 明 过 upstream 机 制 的 一 种 基础 用 法 ， 本 章 将 讨论 upstream 机 制 的 设计 
和 实现 ， 以 此 帮助 读者 全 面 了 解 如 何 使 用 upstream 访 问 上 游 服 务 器 。upstream 机 制 是 事件 驱动 
框架 与 HTTP 框架 的 综合 ， 它 既 属 于 HTTP 框 架 的 一 部 分 ， 又 可 以 处 理 所 有 基于 TCP 的 应 用 层 
协议 〈 不 限于 HITP) 。 它 不 仅 没 有 任何 阻塞 地 实现 了 Nginx 与 上 游 服务 器 的 交互 ， 同 时 又 很 
好 地 解决 了 一 个 请 求 、 多 个 TCP 连 接 、 多 个 读 / 写 事件 间 的 复杂 关系 。 为 了 帮助 Nginx 实 现 反 
向 代理 功能 ，upstream 机 制 除了 提供 基本 的 与 上 游 交 互 的 功能 之 外 ， 还 实现 了 转发 上 游 应 用 
层 协议 的 响应 包 体 到 下 游客 户 端的 功能 〈 与 下 游 之 间 当 然 还 是 使 用 HTTP) 。 在 这 些 过 程 
中 ，upstream 机 制 使 用 内 存 时 极其 “节省 ”， 特 别 是 在 转发 响应 包 体 时 ， 它 从 不 会 把 一 份 上 游 
的 协议 包 复制 多 份 。 考 虑 到 上 下 游 间 网 速 的 不 对 称 ，upstream 机 制 还 提供 了 以 大 内 存 和 磁盘 
文件 来 缓存 上 游 响 应 的 功能 。 











因此 ， 拥 有 高 性 能 、 高 效率 以 及 高 度 灵 活性 的 upstream 机 制 值 得 我 们 花费 精力 去 了 解 它 
的 设计 、 实 现 ， 这 样 才能 更 好 地 使 用 它 。 同 时 ， 通 过 学 习 它 的 设计 思想 ， 也 可 以 深入 了 人 解 配 
合 应 用 层 业 务 基 于 第 9 章 的 事件 框架 开发 Nginx 模 块 的 方法 。 














由 于 upstream 机 制 较为 复杂 ， 同 时 在 第 11 章 “HTTP 框 架 ” 中 我 们 已 经 非常 熟悉 如 何 使 用 事 
件 驱动 架构 了 ， 所 以 本 章 将 不 会 纠结 于 事件 驱动 架构 的 细节 、 分 支 ， 而 是 专注 于 upstream 机 
制 的 主要 流程 。 也 就 是 说 ， 本 章 将 会 略 过 处 理 upstream 的 过 程 中 超时 、 连 接 关 闭 、 失 败 后 重 
新 执行 等 非 核心 事件 ， 仅 聚焦 于 正常 的 处 理 过 程 〈 在 由 源 代码 对 应 的 流程 图 中 ， 就 是 会 把 许 
多 执行 失败 的 分 支 略 过 ， 对 于 这 些 错误 分 支 的 执行 情况 ， 读 者 可 以 通过 阅读 
ngx_http_upstream 源 代码 来 了 解 ) 。 虽 然 upstream 机 制 也 包含 了 部 分 文件 缓存 功能 的 代码 ， 但 
限于 篇 幅 ， 本 章 将 不 介绍 文件 缓存 ， 这 部 分 内 容 也 会 直接 略 过 。 经 过 这 样 处 理 ， 读 者 就 可 以 
清晰 、 直 观 地 看 到 upstream 到 底 是 如 何 工 作 的 了 ， 如 果 还 需要 了 解 细节 ， 那 么 可 以 由 主要 流 
程 附 近 的 相关 代码 查询 到 各 种 分 支 的 处 理 方式 。 
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Nginx 访 问 上 游 服务 器 的 流程 大 致 可 以 分 为 以 下 6 个 阶段 : 有 启动 upstream 机 制 、 连 接 上 游 
服务 器 、 癌 上 游 服务 器 发 送 请 求 、 接 收 上 游 服务 需 的 啊 应 包头 、 处 理 接 收 到 的 啊 应 包 体 、 结 
束 请 求 。 本 章 首先 在 12.1 节 系统 地 讨论 upstream 机 制 的 设计 目的 ， 以 及 为 了 实现 这 些 目的 需 
要 用 到 的 数据 结构 ， 之 后 会 按照 顺序 介绍 上 述 6 个 阶段 。 
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12.1 _upstream 机 制 概 述 


本 节 将 说 明 upstream 机 制 的 设计 目的 ， 包 括 它 能 够 解决 哪 几 类 问题 。 接 下 来 就 会 介绍 一 
个 关键 结构 体 ngx http upstream t 以 及 它 的 conf 成 员 (ngx http_upstream conf t 结 构 体 ) ， 事 实 
上 这 两 个 结构 体 中 的 各 个 成 员 意义 有 些 混淆 不 清 ， 有 些 仅 用 于 upstream 框 架 使 用 ， 有 些 却 是 
希望 使 用 upstream 的 HTTP 模 块 来 设置 的 ， 这 也 是 C 语 言 编 程 的 次 端 。 因 此 ， 如 果 希 望 直接 编 
写 使 用 upstream 机 制 的 复杂 模块 ， 可 以 采取 顺序 阅读 的 方式 ， 如 果 希 望 更 多 地 了 解 upstream 的 
工作 流程 ， 则 不 妨 先 跳 过 对 这 两 个 结构 体 的 详细 说 明 ， 继 续 向 下 了 解 upstream 流 程 ， 在 流程 
的 每 个 阶段 中 都 会 使 用 到 这 两 个 结构 体 中 的 成 员 ， 到 时 可 以 再 返回 查询 每 个 成 员 的 意义 ， 这 
样 会 更 有 效率 。 























12.1.1 .设计 目的 


那么 ， 到 底 什么 是 upstream 机 制 ? 它 的 设计 目的 有 哪些 ? 先 来 看 看 图 12-1。 
(1〉 上 游 和 下 游 


图 12-1 中 出 现 了 上 游 和 下 游 的 概念 ， 这 是 从 Nginx 视 角 上 得 出 的 名 词 ， 怎 么 理解 呢 ? 我 
们 不 妨 把 它 看 成 一 条 产业 链 ，Nginx 是 其 中 的 一 环 ， 离 消费 者 近 的 环节 属于 下 游 ， 离 消费 者 
远 的 环节 属于 上 游 。Nginx 的 客户 端 可 以 是 一 个 浏览 器 ， 或 者 是 一 个 应 用 程序 ， 又 或 者 是 一 
个 服务 器 ， 对 于 Nginx 来 说 ， 它 们 都 属于 “下 游 "”，Nginx 为 了 实现 “下 游 ? 所 需要 的 功能 ， 很 多 
时 候 是 从 “上 游 ” 的 服务 器 获取 一 些 原 材料 的 《如 数据 库 中 的 用 户 信息 等 ) 。 图 12-1 中 的 两 个 
英文 单词 ，upstream 表 示 上 游 ， 而 downstream 表 示 下 游 。 因 此 ， 所 谓 的 upstream 机 制 就 是 用 来 
使 HITP 模 块 在 处 理 客户 端 请 求 时 可 以 访问 "上游 ” 的 后 端 服务 器 。 
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洛 户 师 (Nasinx 的 下 洲 ) 





[HTTP 请 求 ] [基于 HTTP 的 downstream 啊 应 ] 





| 其 于 TCP 的 请 求 | | 基于 TCP upstream | hy | 


后 妆 服 务 需 ( Nginx 的 上 游 





图 12-1 upstream 机制 的 场景 示 意图 
(2) 上 游 服务 器 提供 的 协议 


Nginx 不 仅仅 可 以 用 做 Web 服 务 器 。upstream 机 制 其实 是 由 ngx_http_upstream _ module 模块 
实现 的 ， 它 是 一 个 HTTP 模 块 ， 使 用 upstream 机 制 时 客户 端的 请 求 必 须 基 于 HTTP。 


既然 upstream 是 用 于 访问 “上 游 ?服务 器 的 ， 那 么 ，Nginx 需 要 访问 什么 类 型 的 “上 游 ?服务 


器 昵 ? 是 Apache、Tomcat 这 样 的 Web 服 务 器 ， 还 是 memcached、cassandra 这 样 的 Key-Value 存 
储 系统 ， 又 或 是 mongoDB、MySQL 这 样 的 数据 库 ? 这 吏 涉 及 upstream 机 制 的 范围 了 。 其 实 非 
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常 明显 ， 回 顾 一 下 第 9 章 中 系统 介绍 过 的 主要 用 于 处 理 TCP 的 事件 驱动 架构 ， 基 于 事件 驱动 
架构 的 upstream 机 制 所 要 访问 的 就 是 所 有 支持 TCP 的 上 游 服 务 器 。 因 此 ， 既 有 
ngx_http_proxy_module 模 块 基 于 upstream 机 制 实 现 了 HTTP 的 反问 代理 功能 ， 也 有 类 似 

ngx http_ memcached module 的 模块 基于 upstream 机 制 使 得 请 求 可 以 访问 memcached 服 务 器 。 





(3) 每 个 客户 端 请 求实 际 上 可 以 同 多 个 上 游 服务 器 发 起 请 求 


在 图 12-1 中 ， 似 乎 一 个 客户 端 请 求 只 能 访问 一 个 上 游 服 务 器 ， 事 实 上 并 不 是 这 样 ， 否 则 
Nginx 的 功能 就 太 弱 了 。 对 于 每 个 ngx http request t 请 求 来 说 ， 只 能 访问 一 个 上 游 服 务 器 ， 但 
对 于 一 个 客户 端 请 求 来 说 ， 可 以 派生 出 许多 子 请 求 ， 任 何 一 个 子 请 求 都 可 以 访问 一 个 上 游 服 
务 器 ， 这 些 子 请 求 的 结果 组 合 起 来 就 可 以 使 来 自 客户 端的 请 求 处 理 复杂 的 业务 。 


可 为 什么 每 个 ngx_http_ request t 请 求 只 能 访问 一 个 上 游 服 务 器 ?这 是 由 于 upstream 机 制 还 
有 更 复杂 的 目的 。 以 反 向 代理 功能 为 例 ，upstream 机 制 需要 把 上 游 服 务 器 的 响应 全 部 转发 给 
客户 端 ， 那 么 如 果 响 应 的 长 度 特别 大 怎么 办 ? 例如， 用 户 下 载 一 个 5GB 的 视频 文件 ， 
upstream 机 制 肯 定 不 能 够 在 Nginx 接 收 了 完整 的 响应 后 ， 再 把 它 转 发 给 客户 端 ， 这 样 效 率 太 差 
了 。 因 此 ，upstream 机 制 不 只 提供 了 直接 处 理 上 游 服务 器 响应 的 功能 ， 还 具有 将 来 自 上 游 服 
务 器 的 啊 应 即时 转发 给 下 游客 户 端的 功能 。 因 为 有 了 这 个 独特 的 需求 ， 每 个 
ngx_http_request t 结 构 体 只 能 用 来 访问 一 个 上 游 服 务 器 ， 大 大 简化 了 设计 。 





(4) 反问 代理 与 转发 上 游 服务 器 的 啊 应 





转发 啊 应 时 同样 有 两 个 需要 解决 的 问题 。 


1) 下 游 协议 是 HTTP， 而 上 游 协 议 可 以 是 基于 TCP 的 任何 协议 ， 这 需要 有 一 个 适 配 的 过 
程 。 所 以 ，upstream 机 制 会 将 上 游 的 啊 应 划分 为 包头 、 包 体 两 部 分 ， 包 头 部 分 必须 由 HITP 模 
块 实现 的 process_header 方 法 解析 、 处 理 ， 包 体 则 由 upstream 不 做 修改 地 进行 转发 。 


2) 上 、 下 游 的 网 速 可 能 差别 非常 大 ， 通 常 在 产品 环境 中 ，Nginx 与 上 游 服务 器 之 间 是 内 
NNn httpo://ww linuxorobe. con 











会 很 快 ， 而 Nginx 与 下 游 的 客户 端 之 间 则 是 公 网 ， 网 速 可 能 非常 慢 。 对 于 这 种 情 
有 以 下 两 种 解决 方案 : 


网 ， 网 速 
会 


况 ， 将 


- 当 上 、 下 游 网 速 差距 不 大 ， 或 者 下 游 速度 更 快 时 ， 出 于 能 够 并 发 更 多 请 求 的 考虑 ， 必 
然 希 望 内 存 可 以 使 用 得 少 一 些 ， 这 时 将 会 开辟 一 块 固定 大 小 的 内 存 〈 由 
ngx_http_upstream_conf_t 中 的 buffer_size 指 定 大 小 ) ， 既 用 它 来 接收 上 游 的 响应 ， 也 用 它 来 把 
保存 的 响应 内 容 转发 给 下 游 。 这 样 做 也 是 有 缺点 的 ， 当 下 游 速度 过 慢 而 导致 这 块 充 当 缓 冲 区 
的 内 存 写 满 时 ， 将 无 法 再 接收 上 游 的 响应 ， 必 须 等 待 缓 冲 区 中 的 内 容 全 部 发 送 给 下 游 后 才能 
继续 接收 。 


当 上 游 网 速 远 快 于 下 游 网 速 时 ， 就 必须 要 开辟 足够 的 内 存 缓冲 区 来 缓存 上 游 响 应 
(ngx_http_upstteam_conf t 中 的 bufs 指 定 了 每 块 内 存 缓冲 区 的 大 小 ， 以 及 最 多 可 以 有 多 少 块 
内 存 缓 冲 区 ) ， 当 达到 内 存 使 用 上 限时 还 会 把 上 游 响 应 缓存 到 磁盘 文件 中 (当然 ,磁盘 文件 

也 是 有 大 小 限制 的 ，ngx_http_upstream_conf t 中 的 max_temp_file_ size 指定 了 临时 缓存 文件 的 
最 大 长 度 ) ， 虽 然 内 存 和 磁盘 的 缓冲 都 满 后 ， 仍 然 会 发 生 暂时 无 法 接收 上 游 响应 的 场景 ， 但 
这 种 概率 就 小 得 多 了 ， 特 别 是 临时 文件 的 上 限 设置 得 较 大 时 。 


转发 啊 应 时 一 个 比较 难以 解决 的 问题 是 Nginx 对 内 存 使 用 得 太 “ 节 省 ”， 即 从 来 不 会 把 接 
收 到 的 上 游 啊 应 缓冲 区 复制 为 两 份 。 这 就 市 来 了 一 个 问题 ， 当 同一 块 缓冲 区 既 用 于 接收 上 游 
啊 应 ， 义 用 于 癌 下 游 发 送 啊 应 ， 同 时 可 能 还 在 写 入 临时 文件 ， 那 么 ， 这 块 缓冲 区 何 时 可 以 释 
放 ， 以 便 接收 新 的 缓冲 区 呢 ?” 对 于 这 个 问题 ，Nginx 是 采用 多 个 ngx_buf tt 结构 体 指向 同一 块 
内 存 的 做 法 来 解决 的 ， 并 且 这 些 ngx_buf t 绥 冲 区 的 shadow 域 会 互相 引用 ， 以 确保 真实 的 缓冲 
区 真 的 不 再 使 用 时 才 会 回收 、 复 用 。 








12.1.2 ngx http_ upstream tt 数据 结构 的 意义 





使 用 upstream 机 制 时 必须 构造 ngx_http_upstream t 结 构 体 ， 下 面 详 述 其 中 每 个 成 员 的 意 
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义 。 





typedef struct ngx http upstream s ngx http upstream 七 struct ngx http upstream s { 


// 处 理 读 事件 的 回调 方法 ， 每 一 个 阶段 都 有 不 同 的 


read event handler 








ngx http upstream handler pt read event handler; // 处 理 写 事件 的 回调 方法 ， 每 一 个 阶段 都 有 不 同 的 
write event handler 

ngx http upstream handler pt write event handler; /* 表 示 主 动向 上 游 服 务 器 发 起 的 连接 。 关 于 
ngx peer connection 七 结构 体 ， 可 参见 
9;352 革 

*/ 

ngx peer connection t peer; 

// 当 向 下 游客 户 端 转发 响应 时 
ngx http request t 结 构 体 中 的 
subrequest in memory 标 志 位 为 
0) ， 如 果 打 开 了 缓存 且 认为 上 游 网 速 更 快 〈 
conf 配 置 中 的 
buffering 标 志 位 为 
1) ， 这 时 会 使 用 
Pipe 成 员 来 转发 响应 。 在 使 用 这 种 方式 转发 响应 时 ， 必 须 由 


HTTP 模 块 在 使 用 
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upstream 机 制 前 构造 


Pipe 结 构 体 ， 否 则 会 出 现 严重 的 


coredump 错 误 。 详 见 


12:8:1 节 


yy 


ngx event pipe t *pipe; 


// 定义 了 向 下 游 发 送 响应 的 方式 


ngx output chain ctx 七 output; 





ngx chain writer ctx t writer; 





// 使 用 
upstream 机 制 时 的 各 种 配置 ， 详 见 


tls3 


ngx http upstream conf t *conf; 
/*HTTP 模 块 在 实现 
process_header 方 法 时 ， 如 果 希 望 
upstream 直 接 转 发 响应 ， 就 需要 把 解析 出 的 响应 头 部 适 配 为 
HTTP 的 响应 头 部 ， 同 时 需要 把 包头 中 的 信息 设置 到 


heaqders_in 结 构 体 中 ， 这 样 ， 在 图 
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12-5 的 第 


headers_in 中 设置 的 头 部 添加 到 要 发 送 到 下 游客 户 端的 响应 头 部 


headers_ out 中 


G4 


ngx http upstream headers in t headers in; // 用 于 解析 主机 域名 ， 本 章 不 作 介绍 


ngx_http_upstream resolved t *resolved; /* 接 收 上 游 服务 器 响应 包头 的 缓冲 区 ， 在 不 需要 把 响应 直接 转发 给 客户 端 ， 或 者 





buffering 标 志 位 为 
0 的 情况 下 转发 包 体 时 ， 接 收 包 体 的 缓冲 区 仍然 使 用 
puffer。 注 意 ， 如 果 没有 自 定义 
input filter 方法 处 理 包 体 ， 将 会 使 用 
buffer 存 储 全 部 的 包 体 ， 这 时 
buffer 必 须 足 够 大 ! 它 的 大 小 由 
ngx http upstream conf t 配 置 结构 体 中 的 
buffer size 成 员 决 定 
ff 
ngx buf t buffer; 


// 表示 来 自 上 游 服务 器 的 响应 包 体 的 长 度 
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/* out bufs 在 两 种 场景 下 有 不 同 的 意义 : 四 当 不 需要 转发 包 体 ， 且 使 用 默认 的 


input filter 方法 (也 就 是 


ngx http upstream non buffered _ filter 方法 ) 处 理 包 体 时 ， 





out_bufs 将 会 指向 响应 包 体 ， 事 实 上 ， 


out_bufs 链 表 中 会 产生 多 个 


ngx_ buf tt 缓冲 区 ， 每 个 缓冲 区 都 指向 


buffer 缓 存 中 的 一 部 分 ， 而 这 里 的 一 部 分 就 是 每 次 调用 


recv 方 法 接收 到 的 一 段 


TCP 流 。 回 当 需 要 转发 响应 包 体 到 下 游 时 ( 


buffering 标 志 位 为 


0， 即 以 下 游 网 速 优先 ， 参 见 


12.7 节 ) ， 这 个 链表 指向 上 一 次 向 下 游 转 发 响应 到 现在 这 段 时 间 内 接收 自 上 游 的 缓存 响应 





*] 
ngx chain 七 xout bufs; 
/* 当 需要 转发 响应 包 体 到 下 游 时 ( 
buffering 标 志 位 为 
0， 即 以 下 游 网 速 优先 ， 参 见 
12.7 节 ) ， 它 表示 上 一 次 向 下 游 转发 响应 时 没有 发 送 完 的 内 容 
人 
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/* 这 个 链表 将 用 于 回收 


out_bufs 中 已 经 发 送 给 下 游 的 


ngx_buf 结构 体 ， 这 同样 应 用 在 


buffering 标 志 位 为 


0 即 以 下 游 网 速 优先 的 场景 


*/ 
ngx chain t *free bufs; 
/* 处 理 包 体 前 的 初始 化 方法 ， 其 中 
data 参 数 用 于 传递 用 户 数据 结构 ， 它 实际 上 就 是 下 面 的 
input filter ctx 指 针 
4 


ngx int t (*input filter init) (void *data); /* 处 理 包 体 的 方法 ， 其 中 


data 参 数 用 于 传递 用 户 数 据 结 构 ， 它 实际 上 就 是 下 面 的 


input _ filter ctx 指 针 ， 而 


bytes 表 示 本 次 接收 到 的 包 体 长 度 。 返 回 


NGX_ERROR 时 表示 处 理 包 体 错误 ， 请 求 需要 结 来 ， 否 则 都 将 继续 





upstream 流 程 
#/ 


ngx int t (*input filter) (void *data, ssize t bytes); /* 用 于 传递 
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input filter init 和 


ijnput filter 方法 被 回调 时 会 作为 参数 传递 过 去 


* 


void *input filter ctx; 


// HTTP 模 块 实现 的 


create reduest 方 法 用 于 构造 发 往 上 游 服务 器 的 请 求 


ngx int t (*create request) (ngx http request 七 *r); /x* 与 上 游 服务 器 的 通信 失败 后 ， 如 果 按 照 重 试 规则 还 需要 再 次 向 上 游 服务 


reinit request 方法 


*/ 


ngx int t (*reinit request) (ngx http request 七 *r); /* 解 析 上 游 服务 器 返回 响应 的 包头 ,返回 


NGX_AGAIN 表 示 包 头 还 没有 接收 完整 ， 返 回 





NGX HTTP _ UPSTREAM INVALID HEADER 表 示 包 头 不 合法 ， 返 回 














NGX_ERROR 表 示 出 现 错误 ， 返 回 





NGX_OK 表 示 解 析 到 完整 的 包头 
X/ 
ngx int t (*process header) (ngx http request t *r); // 当前 版 本 下 
abort request 回 调 方法 没有 任意 意义 ， 在 


upstream 的 所 有 流程 中 都 不 会 调用 
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void (*abort request) (ngx http _ request 七 *r); // 请 求 结 束 时 会 调用 ， 参 见 


12.9.1 节 


void (*finalize request) (ngx http request t *r, ngx int t rc); 


/* 在 上 游 返 回 的 响应 出 现 


Location 或 者 





Refresh 头 部 表示 重 定向 时 ， 会 通过 
ngx http upstream process headers 方 法 (参见 图 
12-5 中 的 第 
8 步 ) 调用 到 可 由 
HTTP 模 块 实现 的 
rewrite redirect 方 法 
#/ 


ngx int t (*rewrite redirect) (ngx http request 七 *r, ngx table elt t *h, size 七 prefix); // 暂 无 意义 


ngx msec t timeout; 


// 用 于 表示 上 游 响 应 的 错误 码 、 包 体 长 度 等 信息 


ngx http upstream state t *state; 


// 不 使 用 文件 缓存 时 没有 意义 
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ngx_ str 七 method; 
// schema 和 


uri 成 员 仅 在 记录 日 志 时 会 用 到 ， 除 此 以 外 没有 意义 


ngx_ str t schema; 

ngx_ str t uri; 

/* 目 前 它 仅 用 于 表示 是 否 需要 清理 资源 ， 相 当 于 一 个 标志 位 ， 实 际 不 会 调用 到 它 所 指向 的 方法 
*/ 

ngx http cleanup pt *cleanup; 


// 是 否 指定 文件 缓存 路 径 的 标志 位 ， 本 章 不 讨论 文件 缓存 ， 略 过 


unsigned store:1; 
// 是 否 启 用 文件 缓存 ， 本 章 仅 讨论 
cacheable 标 志 位 为 


0 的 场景 


unsigned cacheable:1; 
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SSL 协 议 访问 上 游 服务 器 


unsigned ssl:1; 


/* 向 下 游 转发 上 游 的 响应 包 体 时 ， 是 否 开启 更 大 的 内 存 及 临时 磁盘 文件 用 于 缓存 来 不 及 发 送 到 下 游 的 响应 包 体 


4 


unsigned buffering:1; 


/*request bufs 以 链表 的 方式 把 


ngx_buf tt 缓冲 区 链接 起 来 ， 它 表示 所 有 需要 发 送 到 上 游 服务 器 的 请 求 内 容 。 所 以 ， 


HTTP 模 块 实现 的 


create request 回 调 方 法 就 在 于 构造 


request bufs 和 链表 


4 


ngx chain t *request bufs; 


/*request sent 表 示 是 否 已 经 向 上 游 服务 器 发 送 了 请 求 ， 当 


request sent 为 


1 时 ， 表 示 


upstream 机 制 已 经 向 上 游 服 务 器 发 送 了 全 部 或 者 部 分 的 请 求 。 事 实 上 ， 这 个 标志 位 更 多 的 是 为 了 使 用 


ngx_output_chain 方 法 发 送 请 求 ， 因 为 该 方法 发 送 请 求 时 会 自动 把 未 发 送 完 的 





request bufs 链 表 记 录 下 来 ， 为 了 防止 反复 发 送 重复 请 求 ， 必 须 有 
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request _sent 标 志 位 记录 是 否 调 用 过 


ngx_output_chain 方 法 


84 


unsigned request sent:1; 


/* 将 上 游 服 务 器 的 响应 划分 为 包头 和 包 尾 ， 如 果 把 响应 直接 转发 给 客户 端 ， 


4 


header sent 标 志 位 表示 包头 是 否 


发 送 ， 


header sent 为 


1 时 表示 已 经 把 包头 转发 给 客户 端 了 。 如 果 不 转发 响应 到 客户 端 ， 则 


header sent 没 有 意义 


4 


unsigned header sent:1; 





到 目前 为 止 ，ngx_http _ upstream t 结 构 体 中 有 些 成 员 仍然 没有 使 月 


12.1.3 ngx _http_upstream conf {配置 结构 体 


到 ， 还 有 更 多 的 成 员 其 实 仅 是 HTTP 框 架 自 己 使 用 








ngx_http_upstream t 结 构 体 中 的 conf 成 员 是 非常 关键 的 ， 它 指定 了 upstream 的 运行 方式 。 注 意 ， 它 必须 在 启动 upstrean 





上 作 村 由 Ptto: /ww inuxorobe. con 





/* 当 在 


ngx http upstream t 结构 体 中 没有 实 现 


resolved 成 员 时 5 


upstream 这 个 结构 体 才 会 生 效 ， 它 会 定义 上 游 服务 器 的 配置 


ngx http upstream srv conf 七 *upstream; /* 建 


TCP 连 接 的 超时 时 间 ， 实 际 上 就 是 写 事件 添加 到 定时 器 中 时 设置 的 超时 时 间 ， 参 见 图 


12-3 中 的 第 


8 步 


A 


ngx msec t connect timeout; 





/* 发 送 请 求 的 超时 时 间 。 通 常 就 是 写 事件 添加 到 定时 器 中 设置 的 超时 时 间 ， 参 见 图 


12-4 中 的 第 


3 步 


7 


ngx msec t send timeout; 





/* 接 收 响 应 的 超时 时 间 。 通 常 就 是 读 事件 添加 到 定时 器 中 设置 的 超时 时 间 ， 参 见 图 
12-4 中 的 第 
5 步 
*/ 
ngx msec t read timeout; 


// 目前 无 意义 


ngx msec 七 timeout; 


// TCP 的 
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size t send lowat; 
/* 定 义 了 接收 头 部 的 缓冲 区 分 配 的 内 存 大 小 
ngx http upstream t 中 的 
buffer 缓 冲 区 ) ， 当 不 转发 响应 给 下 游 或 者 在 
buffering 标 志 位 为 
0 的 情况 下 转发 响应 时 ， 它 同样 表示 接收 包 体 的 缓冲 区 大 小 
*/ 
size t buffer size; 
1/* 仅 当 
puffering 标 志 位 为 
1， 并 且 向 下 游 转 发 响应 时 生效 。 它 会 设置 到 
ngx_event pipe t 结 构 体 的 
busy_size 成 员 中 ， 有 具体 含义 参见 
12.8.1 节 
*/ 
size t busy buffers size; 
/* 在 
buffering 标 志 位 为 
1 时 ， 如 果 上 游 速度 快 于 下 游 速 度 ， 将 有 可 能 把 来 自 上 游 的 响应 存储 到 临时 文件 中 ， 而 
max_temp_ file _ size 指定 了 临时 文件 的 最 大 长 度 。 实 际 上 ， 它 将 限制 
ngx_event_pipe t 结 构 体 中 的 
temp_filex/ 


Size 七 max temp file size; 


// 表示 将 缓冲 区 中 的 响应 写 入 临时 文件 时 一 次 写 入 字符 流 的 最 大 长 度 
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size 七 temp file Write size; 


27 六 下 


3 个 成 员 目 前 都 没有 任何 意义 


size t busy buffers size conf; 


size t max temp file size conf; 


Size t temp file write size Confy 


// 以 缓存 响应 的 方式 转发 上 游 服务 器 的 包 体 时 所 使 用 的 内 存 大 小 


ngx_ bufs t bufs; 


/* 针 对 


ngx http upstream 七 结构 体 中 保存 解 析 完 的 包 头 的 


headers in 成 员 四 


ignore_headers 可 以 按照 二 进 制 位 使 得 


upstream 在 转发 包头 时 跳 过 对 某 些 头 部 的 处 理 。 作 为 


32 位 整 型 ， 理 论 上 


ignore headers 最 多 可 以 表示 


32 个 需要 跳 过 不 予 处 理 的 头 部 ， 然而 目 前 


upstream 机 制 仅 提供 
8 个 位 用 于 忽略 
8 个 


HTTP 头 部 的 处 理 ， 包 括 : 


#define NGX HTTP UPSTREAM IGN XA REDIRECT 0x00000002 
#define NGX HTTP UPSTREAM IGN XA EXPIRES 0x00000004 


#define NGX HTTP UPSTREAM IGN EXPIRES 0x00000008 
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define NGX HTTP UPSTREAM IGN CACHE CONTROL 0x00000010 


define NGX HTTP UPSTREAM IGN SET COOKIE 0x00000020 


define NGX HTTP UPSTREAM IGN XA LIMIT RATE 0x00000040 


define NGX HTTP UPSTREAM IGN XA BUFFERING 0x00000080 








define NGX HTTP UPSTREAM IGN XA CHARSET 0x00000100*/ 


ngx uint t ignore headers; 
/* 以 二 进 制 位 来 表示 一 些 错误 码 ， 如 果 处 理 上 游 响 应 时 发 现 这 些 错误 码 ， 那 么 在 没有 将 响应 转发 给 下 游客 户 端 时 ， 将 会 选择 下 一 个 上 游 服 务 器 
12.9 节 中 介绍 的 
ngx http upstream next 方 法 
*/ 
ngx uint t next upstream; 
/* 在 
puffering 标 志 位 为 
1 的 情况 下 转发 响应 时 ， 将 有 可 能 把 响应 存放 到 临时 文件 中 。 在 
ngx http upstream t 中 的 
store 标 志 位 为 
1 时 ， 
store_access 表 示 所 创建 的 目录 、 文 件 的 权限 
*/ 
ngx uint t store access; 
/* 决 定 转 发 响应 方式 的 标志 位 ， 
buffering 为 
1 时 表示 打开 缓存 ， 这 时 认为 上 游 的 网 速 快 于 下 游 的 网 速 ， 会 尽量 地 在 内 存 或 者 磁盘 中 缓存 来 自 上 游 的 响应 ; 如 果 
buffering 为 


0， 仅 会 开辟 一 块 国定 大 小 的 内 存 块 作为 缓存 来 转发 响应 
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ngx flag t buffering; 


// 暂 无 意义 


ngx flag t pass request headers; 


好 :者 无 意 头 


ngx flag t pass_ request body; 


1 时 ， 表 示 与 上 游 服 务 器 交互 时 将 不 检查 


Nginx 与 下 游客 户 端 间 的 连接 是 否 断 开 。 也 就 是 说 ， 即 使 下 游客 户 端 主动 关闭 了 连接 ， 也 不 会 中 断 与 上 游 服务 器 间 的 交互 


*/ 
ngx flag t ignore client abort; 
/* 当 解析 上 游 响 应 的 包头 时 ， 如 果 解 析 后 设置 到 
headers in 结构 体 中 的 
status_n 错 误 码 大 于 
400， 则 会 试图 把 它 与 
error_page 中 指定 的 错误 码 相 匹配 ， 如 果 匹 配 上 ， 则 发 送 
error_page 中 指定 的 响应 ， 否 则 继续 返回 上 游 服务 器 的 错误 码 。 详 见 
ngx_http upstream intercept errors 方 法 
*/ 


ngx flag t intercept errors; 
/*buffering 标 志 位 为 
1 的 情况 下 转发 响应 时 才 有 意义 。 这 时 ， 如 果 
cyclic temp file 为 
1， 则 会 试图 复 用 临时 文件 中 已 经 使 用 过 的 空间 。 不 建议 将 


cyclic temp file 设 为 
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ngx flag t cyclic temp file; 


// 在 
buffering 标 志 位 为 


1 的 情况 下 转发 响应 时 ， 存 放 临 时 文件 的 路 径 


ngx path t *temp path; 
/* 不 转发 的 头 部 。 实 际 上 是 通过 
ngx_ http upstream hide headers hash 方 法 ， 根 据 
hide headers 和 
pass_headers 动 态 数组 构造 出 的 需要 隐藏 的 
HTTP 头 部 散 列 表 
*/ 
ngx hash t hide headers hash; 
人 * 当 转发 上 游 响 应 头 部 
ngx http upstream t 中 
headers_in 结 构 体 中 的 头 部 ) 给 下 游客 户 端 时 ， 如 果 不 希 望 菜 些 头 部 转发 给 下 游 ， 就 设置 到 
hide headers 动 态 数 组 中 
*/ 
ngx array t *hide headers; 
人 * 当 转发 上 游 响应 头 部 〈 
ngx_http_upstream t 中 
headers_in 结 构 体 中 的 头 部 ) 给 下 游客 户 端 时 ， 
upstream 机 制 默认 不 会 转发 如 “ 


» « 
Date ‘% 


server” 之 类 的 头 部 ， 如 果 确 实 希 望 直接 转发 它们 到 下 游 ， 就 设置 到 


口 岂 所 岂 有 有 和 所 掉 由 http' /wNv inuxorobe. con 





pass_headers 动 态 数组 中 
计 六 
ngx array 七 *pass headers; 


// 连接 上 游 服务 器 时 使 用 的 本 机 地 址 


ngx addr 七 *local; 
/* 当 
ngx_ http upstream t 中 的 
store 标 志 位 为 
1 时 ， 如 果 需 要 将 上 游 的 响应 存放 到 文件 中 ， 
store_lengths 将 表示 存放 路 径 的 长 度 ， 而 
store_values 表 示 存 放 路 径 
x/ 
ngx array t *store lengths; 
ngx array t *store values; 
/* 到 目前 为 止 ， 
store 标 志 位 的 意义 与 
ngx http upstream t 中 的 
store 相 同 ， 仍 只 有 
0 和 
1 被 使 用 到 
*/ 
signed store:2; 
/* 上 面 的 
intercept errors 标 志 位 定义 了 


400 以 上 的 错误 码 将 会 与 
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error_page 比 较 后 再 行 处 理 ， 实 际 上 这 个 规则 是 可 以 有 一 个 例外 情况 的 ， 如 果 将 
intercept 404 标 志 位 设 为 
1， 当 上 游 返回 
404 时 会 直接 转发 这 个 错误 码 给 下 游 ， 而 不 会 去 与 
error_page 进 行 比较 
*/ 
unsigned intercept 404:1; 
/* 当 该 标志 位 为 
1 时 ， 将 会 根据 
ngx_http_upstream t 中 
headers in 结构 体 里 的 
X-aAccel-Buffering 头 部 ( 它 的 值 会 是 
yes 和 
no) 来 改变 
buffering 标 志 位 ， 当 其 值 为 
yes 时 ， 
buffering 标 志 位 为 
1 让 
change buffering 为 
1 时 将 有 可 能 根据 上 游 服务 器 返回 的 响应 头 部 ， 动 态 地 决定 是 以 上 游 网 速 优先 还 是 以 下 游 网 速 优 先 
*/ 
unsigned change buffering:1; 


// 使 用 


upstream 的 模块 名 称 ， 仅 用 于 记录 日 志 
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} ngx_httP_upstream_conf 七 7 


ee | 





ngx_http_upstream_conf t 结 构 体 中 的 配置 都 比较 重要 ， 它 们 会 影响 访问 上 游 服 务 器 的 方式 。 同 时 ， 该 结构 体 中 的 大 量 成 员 是 与 如 何 转 发 上 游 
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12.2 ”局 动 upstream 


在 把 请 求 里 ngx_http request t 结 构 体 中 的 upstream 成 员 (ngx http_upstream t 类 型 ) 创建 并 
设置 好 ， 并 且 正 确 设置 upstream->conf 配 置 结构 体 (ngx_http_upstream conf t 类 型 ) 后 ， 就 可 
以 启动 upstream 机 制 了 。 局 动 方式 非常 简单 ， 调 用 ngx_http_upstream init 方 法 即 可 。 





注意 ， 默 认 情 况 下 请 求 的 upstream 成 员 只 是 NULL 空 指针 ， 在 设置 upstream 之 前 需要 调用 
ngx_http_upstream create 方 法 从 内 存 池 中 创建 ngx_http_upstream t 结 构 体 ， 该 方法 的 原型 如 
下 





ngx _ int t ngx http upstream create (ngxX http request 七 *r) 








ngx_http_upstream create 方 法 只 是 创建 ngx_http_upstream tt 结构 体 而 已 ， 其 中 的 成 员 还 需 
要 各 个 HTTP 模 块 自行 设置 。 启 动 upstream 机 制 的 ngx_http_upstream init 方 法 定义 如 下 。 





void ngx http upstream init (ngx http request t *r) 





ngx http upstream init 方 法 将 会 根据 ngx_http_upstream conf t 中 的 成 员 初 始 化 upstream， 同 
时 会 开始 连接 上 游 服 务 器 ， 以 此 展开 整个 upstream 处 理 流 程 。 图 12-2 人 简要 描述 了 
ngx_http_upstream init 方 法 所 做 的 主要 工作 。 
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[检查 下 游 连接 读 事件 的 timer_ set 标志 位 ] 





[ 读 事 件 在 定时 顺 中 ] 


1 ) 将 客户 端 连 接 的 读 事件 由 [该 事件 不 在 定时 需 中 ] 
定时 需 中 移 除 
[检查 ignore client _abort 配 置 ] 






[ignore_client_abort 为 1] 


[ignore_client_abort 为 0] 


2 ) 设 置 检查 Nginx 
写 下 游客 户 端 连接 状态 的 方法 


3 ) 调 用 HTTP 模 块 实现 的 


create_request 方 法 


4) 将 ngx_http_upstream_cleanup 
方法 添加 到 cleanup 链 表 


5) 调用 ngx_http_upstream_connect 


方法 连接 上 游 服务 前 


® 


图 12-2 ngx_http_upstream_init 方 法 的 流程 图 
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下 面 依次 说 明 图 12-2 中 各 个 步骤 的 意义 。 


1) 首先 检查 请 求 对 应 于 客户 端的 连接 ， 这 个 连接 上 的 读 事 件 如 果 在 定时 器 中 ， 也 就 是 
说 ， 读 事件 的 timer_ set 标志 位 为 1， 那 么 调用 ngx del timer 方 法 把 这 个 读 事件 从 定时 器 中 移 
除 。 为 什么 要 做 这 件 事 呢 ? 因为 一 旦 启动 upstream 机 制 ， 就 不 应 该 对 客户 端的 读 操 作 带 有 超 
时 时 间 的 处 理 ， 请 求 的 主要 触发 事件 将 以 与 上 游 服务 器 的 连接 为 主 。 





2) 检查 ngx http_ upstream conf t 配 置 结构 中 的 ignore_client abort 标 志 位 (参见 12.1.3 
节 ) ， 如 果 ignore_client abort 为 1， 则 跳 到 第 3 步 ， 否 则 《实际 上 ， 还 需要 让 store 标 志 位 为 
0、 请 求 ngx http request t 结 构 体 中 的 post_action 标 志 位 为 0) 就 会 设置 Nginx 与 下 游客 户 端 之 
间 TCP 连 接 的 检查 方法 ， 如 下 所 示 。 





r->read event handler = ngx http upstream rd check broken connection; 
r->write event handler = ngx http upstream wr check broken connection; 











实际 上 ， 这 两 个 方法 都 会 通过 ngx http_ upstream check broken connection 方 法 检查 Nginx 
与 下 游 的 连接 是 否 正 常 ， 如 果 出 现 错误 ， 就 会 并 即 终止 连接 。 


3) 调用 请 求 中 ngx_http_upstream tt 结构 体 里 由 某 个 HTTP 模 块 实现 的 create_request 方 法 ， 
构造 发 往 上 游 服务 器 的 请 求 〈 请 求 中 的 内 容 是 设置 到 request buf 缓冲 区 链表 中 的 ) 。 如 果 
create request 方法 没有 返回 NGX_ OK， 则 upstream 机 制 结束 ， 此 时 会 调用 11.10.6 节 中 介绍 过 
的 ngx http finalize request 方法 来 结束 请 求 。 


4) 在 11.10.2 节 中 介绍 过 ，ngx _http_cleanup t 是 用 于 清理 资源 的 结构 体 ， 还 说 明了 它 何 时 
会 被 执行 。 在 这 一 步 中 ，upstream 机 制 就 用 到 了 ngx_phttp_cleanup_ t。 首 先 ， 调 用 
ngx_http_cleanup_add 方 法 同 这 个 请 求 main 成 员 指 同 的 原始 请 求 中 的 tt 二 
新 成 员 ， 然 后 把 handler 回 调 方 法 设 为 ngx http upstream cleanup， 这 意味 着 当 请 求 结 束 时 ， 
定 会 调用 ngx http upstream cleanup 方 法 (参见 12.9.1 节 ) 。 


5) 站 -PP 站 PP Hr 车 接 We 人 











@ 注意 ”启动 upsttream 机 制 时 还 有 许多 分 支流 程 ， 如 缓存 文件 的 使 用 、 上 游 服务 器 地 
址 的 选取 等 ， 图 12-2 概 括 了 最 主要 的 5 个 步骤 ， 这 样 方便 读者 了 解 upstream 的 核心 思想 。 其 他 
分 支 的 处 理 不 影响 这 5 个 主要 流程 ， 如 需 了 解 可 自行 查看 ngx_http_upstream_init 和 


nex_http_upstream_init_request 方 法 的 源 代 码 。 
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12.3 ”与 上 游 服 务 右 建 并 连接 





upstream 机 制 与 上 游 服 务 器 是 通过 TCP 建 立 连 接 的 ， 众 所 周知 ， 建 并 TCP 连 接 需要 三 次 握 
手 ， 而 三 次 握手 消耗 的 时 间 是 不 可 控 的 。 为 了 保证 建立 TCP 连 接 这 个 操作 不 会 阻塞 进程 ， 
Nginx 使 用 无 阻塞 的 套 接 字 来 连接 上 游 服务 器 。 图 12-2 的 第 5 步调 用 的 
ngx_http_upstream_connect 方 法 就 是 用 来 连接 上 游 服 务 器 的 ， 由 于 使 用 了 非 阻 塞 的 套 接 字 ， 当 
方法 返回 时 与 上 游 之 间 的 TCP 连 接 未 必 会 成 功 建立 ， 可 能 还 需要 等 待 上 游 服 务 器 返回 TCP 的 
SYN/ACK 包 。 因 此 ，ngx http upstream connect 方 法 主要 负责 发 起 建立 连接 这 个 动作 ， 如 果 这 
个 方法 没有 立刻 返回 成 功 ， 那 么 需要 在 epoll 中 监控 这 个 套 接 字 ， 当 它 出 现 可 写 事件 时 ， 就 说 
明 连 接 已 经 建立 成 功 了 。 











在 图 12-3 中 可 以 看 到 ， 如 果 连 接 立 刻 成 功 建立 ， 在 第 9 步 就 会 开始 向 上 游 服务 器 发 送 请 
求 ， 如 果 连 接 没 有 马上 建立 成 功 ， 在 第 8 步 就 会 将 这 个 连接 的 写 事件 加 入 到 epoll 中 ， 等 待 连 
接 上 的 可 写 事件 被 触发 后 ， 回 调 ngx http upstream send request 方 法 发 送 请 求 给 上 游 服 务 器 。 


下 面 详细 说 明 图 12-3 中 每 个 步骤 的 意义 。 





1) 调用 socket 方 法 建立 一 个 TCP 套 接 字 ， 同 时 ， 这 个 套 接 字 需 要 设置 为 非 阻 塞 模式 。 








2) 由 于 Nginx 的 事件 框架 要 求 每 个 连接 都 由 一 个 ngx_connection t 结 构 体 来 承载 ， 因 此 这 
一 步 将 调用 ngx get_connection 方 法 ， 由 ngx_cycle t 核 心 结构 体 中 free_connections 指 同 的 空 闻 连 
接 池 处 获取 到 一 个 ngx_connection tf 结构 体 ， 作 为 承载 Nginx 与 上 游 服 务 器 间 的 TCP 连 接 。 


3) 第 9 章 我 们 介绍 过 事件 模块 的 ngx event actions 接 口 ， 其 中 的 add _ conn 方法 可 以 将 TCP 
套 接 字 以 期 待 可 恋 、 可 写 事 件 的 方式 添加 a 到 事件 搜集 器 中 。 对 于 epoll 事 件 模块 来 说 ， 
add conn 方 法 就 是 把 套 接 字 以 期 待 EPOLLINIEPOLLOUT 事 件 的 方式 加 入 epoll 中 ， 这 一 步 即 调 
用 add_conmn 方 法 把 刚刚 建立 的 套 接 字 添加 到 epoll 中 ， 表 示 如 果 这 个 套 接 字 上 出 现 了 预期 的 网 
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络 事件 ， 则 和 希望 epoll 能 够 回调 它 的 handler 方 法 。 
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套 接 字 


2) 由 空闲 连接 池 中 获取 


ngx_connection_t 结 构 体 


3 ) 将 连接 对 应 的 套 接 字 添 加 到 
epoll 中 来 监控 读 / 写 事件 


4 ) 调 用 connect 
方法 连接 上 游 服 务 妖 


5 ) 设 置 连 接 读 / 写 事件 
的 回调 方法 


6 ) 设 置 upstream 机 制 的 
write_event_ handler 方 法 


7) 设置 upstream 机 制 的 
read_event handle 芒 法 


[检测 第 4 步 connect 的 返回 值 ] 











[连接 建立 成 功 ] 
[等 待 上 游 服 务 器 的 返回 ] 


8) 将 连接 的 写 事 件 
添加 到 定时 器 中 


9) 调用 ngx_http_upstream_send_request 


方法 发 送 请 求 
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图 12-3 ”ngx_http_upstream_connect 方 法 的 流程 图 


4) 调用 connect 方 法 向 上 游 服务 器 发 起 TCP 连 接 ， 作 为 非 阻塞 套 接 字 ，connect 方 法 可 能 
立刻 返回 连接 建立 成 功 ， 也 可 能 告诉 用 户 继续 等 竺 上游 服 务 器 的 啊 应 ， 对 connect 连 接 是 人 否 建 
并 成 功 的 检查 会 在 第 7 步 之 后 进行 。 注 意 ， 这 里 并 没有 涉及 connect 返 回 失 败 的 情形 ， 读 者 可 
以 参考 第 11 半 中 这 种 系统 调用 失败 后 的 处 理 ， 本 章 不 会 讨论 细 市 。 





5) 将 这 个 连接 ngx_connection t 上 的 读 / 写 事件 的 handler 回 调 方法 都 设置 为 
ngx http upstream handler。 下 文 会 介绍 ngx http_ upstream handler 方 法 。 


6) 将 upstream 机 制 的 write_event handler 方 法 设 为 
ngx http upstream send request handler。write event handler 和 read_event handler 的 用 法 参见 
下 面 将 要 介绍 的 ngx http upstream handler 方 法 。 这 一 步骤 实际 上 决定 了 加 上 游 服 务 器 发 送 请 


求 的 方法 是 ngx http upstream send request handler。 


7) 设置 upstream 机 制 的 read_event handler 方 法 为 ngx_ http_ upstream process_header， 也 就 
是 由 ngx http upstream process_ header 方 法 接收 上 游 服 务 器 的 响应 。 


现在 开始 检查 在 第 4 步 中 调用 connect 方 法 连接 上 游 服务 器 是 否 成 功 ， 如 宋 已 经 连接 成 
功 ， 则 跳 到 第 9 步 执 行 ， 如 果 尚 未 收 到 上 游 服 务 器 连接 建立 成 功 的 应 答 ， 则 跳 到 第 8 步 执行 。 


8) 这 一 步 处 理 非 阻塞 的 连接 尚未 成 功 建立 时 的 动作 。 实 际 上 ， 在 第 3 步 中 ， 套 接 字 已 经 
加 入 到 epoll 中 监控 了 ， 因 此 ， 这 一 步 将 调用 ngx add timer 方 法 把 写 事件 添加 到 定时 器 中 ， 超 
时 时 间 就 是 12.1.3 节 中 介绍 的 ngx_http_upstream conf t 结 构 体 中 的 connect timeout 成 员 ， 这 是 
在 设置 建立 TCP 连 接 的 超时 时 间 。 


9) 如 果 已 经 成 功 建立 连接 ， 则 调用 ngx http upstream send request 方法 向 上 游 服务 器 发 
送 请 求 。 注 意 ， 在 第 6 步 中 设置 的 发 送 请 求 方法 为 ngx_http_upstream send request handler， 它 
与 ngx_http_upstream send request 方 法 的 不 同 之 处 将 在 12.4 节 中 介绍 。 
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以 上 的 第 5S、 第 6、 第 7 步 都 与 ngx http_upstream handler 方 法 相关 ， 同 时 我 们 又 看 到 了 类 
似 ngx http_ request t 结 构 体 中 write event handler、read event handler 的 同名 方法 。 实 际 上 ， 
ngx_http_upstream handler 方 法 与 图 11-7 展 示 的 ngx_http request handler 方 法 也 非常 相似 ， 下 面 
看 看 它 到 底 做 了 些 什么 。 





static void ngx http upstream handler (ngx event t ev) 


{ 
ngx connection t c; 
ngx http request 七 ry 
ngx http upstream t u; 
/* 由 事件 的 

data 成 员 取 得 


ngx_connection 七 连接 。 注 意 ， 这 个 连接 并 不 是 


Nginx 与 客户 端的 连接 ， 而 是 


Nginx 与 上 游 服 务 器 间 的 连接 


*/ 
C= ev->data; 
// 由 连接 的 
data 成 员 取 得 


ngx_http request 七 结构 体 


G=>datay 


让 
/* 由 请 求 的 
upstream 成 员 取 得 表示 

upstream 机 制 的 


Ngx_ http upstream 七 结构 体 


= r=SUpStream; 


注意 ， 
ngx_http redquest tt 结构 体 中 的 这 个 
connection 连 接 是 客户 端 与 


Nginx 间 的 连接 
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C= r->connection; 
if (ev->write) f{ 


当 


Nginx 与 上 游 服 务 器 间 


TCP 连 接 的 可 写 事件 被 触发 时 ， 





upstream 的 


write event handler 方 法 会 被 调用 


u->write event handler(r, u); 
} else { 
当 


Nginx 与 上 游 服务 器 间 


TCP 连 接 的 可 读 事件 被 触发 时 ， 


upstream 的 


read event handler 方 法 会 被 调用 


u->read event handler(r, u); 
} 
ngx http run posted requests 方 法 正 是 第 





11 章 图 


11-12 所 说 的 方法 。 注 意 ， 这 个 参数 


C 是 来 自 客户 端的 连接 ， 


Post 请 求 的 执行 也 与 图 


11-12 完 全 一 臻 


6 
ngx http run posted requests (c); 





} 


| ee | 
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12.4 ”发 送 请 求 到 上 游 服 务 器 





问 上 游 服务 器 发 送 请 求 是 一 个 阶段 ， 因 为 请 求 的 大 小 是 未 知 的 ， 所 以 及 送 请 求 的 方法 需 
要 被 epoll 调 度 许多 次 后 才 可 能 发 送 完 请 求 的 全 部 内 容 。 在 图 12-3 中 的 第 6 步 将 
ngx_http_upstream t 里 的 write_event handler 成 员 设 为 ngx_http_upstream send Tequest handler 方 
法 ， 也 就 是 说 ， 由 该 方法 负责 反复 地 发 送 请 求 ， 可 是 ， 在 图 12-3 的 第 9 步 又 直接 调用 了 
ngx_http_upstream send_ request 方法 发 送 请 求 ， 那 这 两 种 方法 之 间 有 什么 关系 吗 ? 和 驳 来 看 看 前 
者 的 实现 ， 它 相对 简单 ， 这 里 直接 列举 了 它 的 主要 源 代 码 ， 如 下 所 示 。 








static void ngx http upstream send request handler (ngx http request t r, 
ngx http upstream t u) 





{ 
ngx connection 七 *c; 


// 获取 与 上 游 服务 器 间 表 示 连 接 的 


ngx_connection 七 结构 体 





Cc = uUu->peer.connection; 


// 写 事件 的 


tijmedout 标 志 位 为 


1 时 表示 向 上 游 服务 器 发 送 的 请 求 已 经 超时 


if (c->write->timedout) { 


/* 将 超时 错误 传递 给 








ngx_http_upstream next 方 法 ,该 方法 将 会 根据 允许 的 错误 重 连 策略 决定 : 重新 发 起 连接 执行 
upstream 请 求 ， 或 者 结束 
upstream 请 求 ， 详 见 


12.9.2 节 


ngx http upstream next(r, ur NGX HTTP UPSTREAM FT TIMEOUT); 
return; 


} 
header sent 标 志 位 为 
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Nginx 已 经 把 响应 包头 转发 给 客户 端 了 


IE (u->header sent) { 
事实 上 ， 


header sent 为 


1 时 一 定 是 已 经 解析 完全 部 的 上 游 响应 包头 ， 并 且 开 始 向 下 游 发 送 


HTTP 的 包头 了 。 到 此 ， 是 不 应 该 继续 向 上 游 发 送 请 求 的 ， 所 以 把 


write event handler 设 为 任何 工作 都 没有 做 的 


ngx http upstream dummy handler 方 法 


U->write event handler = ngx http upstream dummy handler; 
// 将 写 事件 添加 到 





epoll 中 


(void) ngx handle write event (c->write, 0); 


// 因为 不 存在 继续 发 送 请 求 到 上 游 的 可 能 ， 所 以 直接 返回 








return; 
} 
// 调用 


ngx http upstream send request 方法 向 上 游 服务 器 发 送 请 求 








ngx http upstream send request(r, u); 





可 见 ，ngx http _ upstream send request handler 方 法 更 多 的 时 候 是 在 检测 请 求 的 状态 ， 而 
实际 负责 发 送 请 求 的 方法 是 ngx http_ upstream send request， 图 12-4 列 出 了 
ngx http upstream send reques 人 t 访 法 的 主要 执行 步骤 。 


下 面 说 明 以 上 8 个 步骤 的 意义 。 


1 ) 调用 ngx_output_chain 方 法 同上 游 服务 器 发 送 ngx_http_upstream t 结 构 体 中 的 
request_ buf 链表， 这 个 方法 对 于 发 送 缓冲 区 构成 的 ngx_chain t 链 表 非 常 有 用 ， 它 会 把 未 发 送 
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完成 的 链表 绥 冲 区 保存 下 来 ， 这 样 束 不 用 每 次 调用 时 都 携带 上 request_bufs 链 表 。 怎 么 理解 
呢 ? 当 第 一 次 调用 ngx_output_chain 方 法 时 ， 需 要 传递 request_bufs 链 表 构 成 的 请 求 ， 如 下 所 


小 。 





rc = ngx output chain(&u->output, u->request bufs); 





这 里 的 u 束 是 请 求 对 应 的 ngx_http_request t 结 构 体 中 的 upstream 成 员 (ngx_http_upstream t 
类 型 ) ， 如 果 ngx_output_chain 一 次 无 法 发 送 完 所 有 的 request_bufs 请 求 内 容 ， 
ngx_output_chain_ctx t 类 型 的 u->output 会 把 未 发 送 完 的 请 求 保 存在 上 自己 的 成 员 中 ， 同 时 返回 
NGX AGAIN。 当 可 写 事 件 再 次 触发 ， 发 送 请 求 时 就 不 需要 再 传递 参数 了 ， 例 如 : 








rc = ngx output chain(&u->output，NULL) ， 





为 了 标识 这 一 点 ，ngx_http_upstream t 结 构 体 中 专门 有 一 个 标志 位 request_sent 表 示 是 否 已 
经 传递 了 request_bufs 绥 冲 区 。 因 此 ， 在 第 一 次 以 request_bufs 作 为 参数 调用 ngx_output_chain 方 
法 后 ，request sent 会 置 为 1。 


2) 检测 写 事件 的 timer_set 标 志 位 ，timer_ set 为 1 时 表示 写 事件 仍然 在 定时 器 中 ， 那 么 这 
一 步 皮 先 把 写 事件 由 定时 器 中 取出 ， 再 由 ngx_ output chain 的 返回 值 决定 是 否 再 次 癌 定 时 峰 中 
加 入 写 事件 ， 那 时 超时 时 间 也 会 重 置 。 
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1) 发 送 缓冲 区 中 的 请 求 内 容 
到 上 游 服务 器 


2 ) 在 写 事件 在 定时 顺 中 则 移 除 


[ 检测 第 1 步 中 ngx_output_chain 方 法 返 值 ] 


<> 


[已 发 送 完全 部 请 求 ， 准 备 接收 响应 ] 


[未 发 送 完全 部 请 求 ] 





3) 将 写 事件 添加 到 定时 带 中 






5 ) 将 读 事 件 添 加 到 定时 震中 


[检测 读 事件 的 ready 标 志 位 ] 4 ) 将 写 事件 添加 到 epoll 中 


‘> 


[如 有 果 套 接 字 缓冲 区 中 有 数据 可 读 ] 





[ 暂 无 响应 可 读 ] 






7 ) 设 置 write_event_handler 方 法 


6) 调用 ngx http _upstream_process_header 





方法 接收 啊 应 头 部 
8 ) 将 写 事件 添加 到 epoll 中 





S 


图 12-4 ngx_http_upstream_send_request 方 法 的 流程 图 





检测 ngx output chain 的 返回 值 ， 返 回 NGX AGAIN 时 表示 还 有 请 求 未 被 发 送 ， 此 时 跳 到 
第 3 步 ， 如 果 返 回 NGX OK， 则 表示 已 经 发 送 完 全 部 请 求 ， 跳 到 第 5 步 执行 。 


示 
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3) 调用 ngx_add_timer 方 法 将 写 事 件 添 加 到 定时 器 中 ， 防 止 发 送 请 求 超时 。 超 时 时 间 惑 
是 ngx_http_upstream conf t 配 置 结构 体 的 send_timeout 成 员 。 


4) 调用 ngx handle write_event 方 法 将 写 事件 添加 到 epoll 中 ， 


ngx http_upstream send request 方 法 结 


5) 如 果 已 经 同上 游 服务 器 及 送 完 全 部 请 求 ， 这 时 将 准备 开始 处 理 啊 应 ， 首 先 把 读 事 件 
添加 到 定时 器 中 检查 接收 啊 应 是 否 超 时 ， 超 时 时 间 就 是 ngx_http_upstream_conf t 瑟 置 结构 体 


的 read timeout 成 员 。 








检测 读 事 件 的 ready 标 志 位 ， 如 果 ready 为 1， 则 表示 已 经 有 啊 应 可 以 读 出 ， 这 时 跳 到 第 6 
步 执 行 ， 如 果 ready 为 0， 则 跳 到 第 7 步 执 行 。 





6) 调用 ngx http upstream process_header 方 法 接收 上 游 服 务 器 的 啊 应 ， 在 12.5 节 中 会 详 
细 讨 论 该 方法 。 


7) 如 果 暂 无 响应 可 读 ， 由 于 此 时 请 求 已 经 全 部 发 送 到 上 游 服 务 器 了 ， 所 以 要 防止 可 写 
事件 再 次 触发 而 又 调用 ngx http upstream send request 方 法 。 这 时 ， 把 write event handler 设 为 
ngx_http_upstream_dummy_handler 方 法 ， 前 文 说 过 ， 该 方法 不 会 做 任何 事情 。 这 样 即使 与 上 游 
间 的 TCP 连 接 上 再 次 有 可 写 事件 时 也 不 会 有 任何 动作 发 生 ， 它 就 像 第 11 章 我 们 介绍 的 
ngx http empty handler 方 法 。 





8) 调用 ngx handle write _event 方 法 将 写 事 件 加 入 到 epoll 中 。 


在 发 送 请 求 到 上 游 服 务 器 的 这 个 阶段 中 ， 每 当 TCP 连 接 上 再 次 可 以 发 送 字 符 流 时 ， 虽 然 
事件 框架 就 会 回调 ngx http upstream send request handler 方 法 处 理 可 写 事件 ， 但 最 终 还 是 通 
过 调用 ngx http upstream send request 方 法 把 请 求 发 送出 去 的 。 
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12.5 ”接收 上 游 服 务 器 的 啊 应 涉 部 


当 请 求全 部 发 送 给 上 游 服 务 器 时 ，Nginx 开 始 准 备 接收 来 自 上 游 服 务 器 的 啊 应 。 在 图 12- 
3 的 第 7 步 中 设置 了 由 ngx http upstream process_header 方 法 处 理 上 游 服 务 器 的 响应 ， 而 图 12-4 
的 第 8 步 也 是 通过 调用 该 方法 接收 啊 应 的 ， 本 市 的 内 容 就 在 于 说 明 可 能 会 被 反复 多 次 调用 的 
ngx http upstream process header 方 法 。 





12.5.1 ”应 用 层 协 议 的 两 段 划分 方式 


在 12.1.1 节 我 们 已 经 了 解 到 ， 只 要 上 游 服务 器 提供 的 应 用 层 协 议 是 基于 TCP 实 现 的 ， 那 
么 upstream 机 制 都 是 适用 的 。 基 于 TCP 的 响应 其 实 就 是 有 顺序 的 数据 流 ， 那 么 ，upstream 机 制 
只 需要 按照 接收 到 的 顺序 调用 HTTP 模 块 来 解析 数据 流 不 就 行 了 吗 ? 多 么 简单 和 清晰 ! 然 
而 ， 实 际 上 ， 应 用 层 协议 要 比 这 复杂 得 多 ， 这 主要 表现 在 协议 长 度 的 不 可 确定 和 协议 内 容 的 
解析 上 。 首 先 ， 应 用 层 协议 的 响应 包 可 大 可 小 ， 如 最 小 的 响应 可 能 只 有 128B， 最 大 的 响应 可 
能 达到 5GB， 如 果 属 于 HTTP 框 架 的 ngx http_upstream module 模 块 在 内 存 中 接收 到 全 部 响应 内 
容 后 再 调用 各 个 HITP 模 块 处 理 啊 应 ， 就 很 容易 引发 OutOfMemory 错 误 ， 即 使 没有 错误 也 会 因 
为 内 存 消耗 过 大 从 而 降低 了 并 发 处 理 能 力 。 如 果 在 磁盘 文件 中 接收 全 部 响应 ， 又 会 带 来 大 量 
的 磁盘 IO 操作 ， 最 终 大 幅 提高 服务 器 的 负载 。 其 次 ， 对 响应 中 的 所 有 内 容 都 进行 解析 并 无 
必要 《解析 操作 毕竟 对 CPU 是 有 消耗 的 ) 。 例 如 ， 从 Memcached 服 务 器 上 下 载 一 幅 图 片 ， 
Nginx 只 需要 解析 Memcached 协 议 ， 并 不 需要 解析 图 片 的 内 容 ， 对 于 图 片 内 容 ，Nginx 只 需要 
边 接收 边 转发 给 客户 端 即 可 。 














为 了 解决 上 述 问题 ， 应 用 层 协 议 通常 都 会 将 请 求 和 啊 应 分 成 两 部 分 : 包头 和 包 体 ， 其 中 
包头 在 前 而 包 体 在 后 。 包 头 相当 于 把 不 同 的 协议 包 之 间 的 共同 部 分 抽象 出 来 ， 不 同 的 数据 包 
之 间 包 头 都 具备 相同 的 格式 ， 服 务 器 必须 解析 包头 ， 而 包 体 则 完全 不 做 格式 上 的 要 求 ， 服 务 


器 人 SN 











以 内 《〈 例 如， 类似 Apache 这 样 的 Web 服 务 器 默认 情况 下 仅 接 收 包 头 小 于 4KB 的 HITTP 请 求 ) ， 
而 包 体 的 长 度 则 非常 灵活 ， 可 以 非常 大 ， 也 可 以 为 0。 对 于 Nginx 服 务 器 来 说 ， 在 
process_header 处 理 包头 时 ， 需 要 开辟 的 内 存 大 小 只 要 能 够 容纳 包头 的 长 度 上 限 即 可 ， 而 处 
理 包 体 时 需要 开辟 的 内 存 大 小 情况 较 复 杂 ， 可 参见 12.6 节 ~12.8 玉 。 


包头 和 包 体 存储 什么 样 的 信息 完全 取决 于 应 用 层 协 议 ， 包 头 中 的 信息 通常 必须 包含 包 体 
的 长 度 ， 这 是 应 用 层 协议 分 为 包头 、 包 体 两 部 分 的 最 主要 原因 。 很 多 包头 还 会 包含 协议 版 
本 、 请 求 的 方法 类 型 、 数 据 包 的 序列 号 等 信息 ， 这 些 是 upstream 机 制 并 不 关心 的 ， 它 已 经 在 
ngx_http_upstream t 结 构 体 中 抽象 出 了 process_header 方 法 ， 由 具体 的 HTTP 模 块 实现 的 
process_header 来 解析 包头 。 实 际 上 ，upstream 机 制 并 没有 对 HTTP 模 块 怎 样 实现 
process_header 方 法 进行 限制 ， 但 如 果 HTTP 模 块 的 目的 是 实现 反 向 代理 ， 不 妨 将 接收 到 的 包 
头 按 照 上 游 的 应 用 层 协议 与 HTTP 的 关系 ， 把 解析 出 的 一 些 头 部 适 配 到 ngx http_upstream t 结 
构 体 中 的 headers in 成 员 中 ， 这 样 ，upstream 机 制 在 图 12-5 的 第 8 步 就 会 自动 地 调用 
ngx_http_upstream process_headers 方 法 将 这 些 头 部 设置 到 发 送 给 下 游客 户 端的 HITP 啊 应 包头 
中 。 

















包 体 的 内 容 往往 较为 简单 ， 当 HTTP 模 块 希望 实现 反问 代理 功能 时 大 都 不 希望 解析 包 
体 。 这 样 的 话 ，upstream 机 制 基于 这 种 最 常见 的 需求 ， 把 包 体 的 常见 处 理 方式 抽象 出 3 类 加 以 
实现 ，12.5.2 节 中 将 介绍 这 3 种 包 体 的 处 理 方式 。 





12.5.2 ”处 理 包 体 的 3 种 方式 





为 什么 upstream 机 制 不 是 仅仅 负责 接收 上 游 服务 器 发 来 的 包 体 ， 再 交 由 HTTP 模 块 决 定 如 
何 处 理 这 个 包 体 呢 ? 这 是 因为 upstream 有 一 个 最 重要 的 使 命 要 完成 ! Nginx 作 为 一 个 试图 取代 
Apache 的 Web 服 务 器 ， 最 基本 的 反 向 代理 功能 是 必须 存在 的 ， 而 实现 反 向 代理 的 Web 服 务 器 
并 不 仅仅 希望 可 以 访问 上 游 服 务 器 ， 它 更 希望 upstream 能 够 实现 透 传 、 转 发 上 游 响 应 的 功 


能 。 
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upstream 机 制 不 关心 如 何 构造 发 送 到 上 游 的 请 求 内 容 ， 这 事实 上 是 由 各 个 使 用 upstream 的 
HTTP 模 块 实现 的 create_ request 方法 决定 的 〈 目 前 的 HITP 反 辐 代 理 模块 是 这 么 做 的 : Nginx 将 
客户 并 的 请 求全 部 接收 后 再 透 传 给 上 游 服务 占 ， 这 种 方式 很 镜 蛙 ， 又 对 减轻 上 游 服 务 器 的 并 
发 负载 很 有 帮助 ) ， 但 对 啊 应 的 处 理 就 比较 复杂 了 了， 下面 举 两 个 例子 来 说 明 其 复杂 性 。 











如 果 Nginx 与 上 游 服 务 器 间 的 网 速 很 快 〈 例 如 ， 两 者 都 在 一 个 机 房 的 内 网 中 ， 或 者 两 者 
间 拥 有 专线 ) ， 而 Nginx 与 下 游 的 客户 站 间 网 速 又 很 慢 例如， 下 游客 户 端 通过 公 网 访问 机 
房 内 的 Nginx〉， 这 样 就 会 导致 Nginx 接 收 上 游 服 务 器 的 啊 应 非常 快 ， 而 向 下 游客 尸 端 转发 啊 
应 时 很 慢 ， 这 也 就 为 upstream 机 制 带 来 一 个 需求 : 应 当 尽 可 能 地 把 上 游 服务 器 的 啊 应 接收 到 
Nginx 服 务 器 上 ， 包 括 将 来 目 上 游 的 、 还 没 来 及 发 送 到 下 游 的 包 体 缓存 到 内 存 中 ， 如 宋 使 用 
的 内 存 过 大 ， 达 到 东 个 限制 国 值 后 ， 为 了 降低 内 存 的 消耗 ， 还 需要 把 包 体 缓存 到 磁盘 文件 
中 。 











如 果 Nginx 与 上 游 服务 器 间 的 网 速 较 慢 (假设 是 公 网 线路 ) ， 而 Nginx 与 下 游 的 客户 端 间 
的 网 速 很 快 〈 例 如 ， 客 户 端 其 实 是 Nginx 所 在 机 房 里 的 男 一 个 Web 服 务 占 〉， 这 时 就 不 存在 大 
量 缓存 上 游 啊 应 的 需求 了 ， 完 全 可 以 开辟 一 块 固定 大 小 的 内 存 作为 缓冲 区 ， 一 边 接 收 上 游 响 
应 ,一边 回 下 游 转 友 。 每 当 向 下 游 成 功 转 发 部 分 啊 应 后 就 可 以 复 用 缓冲 区 ， 这 样 既 不 会 消耗 
大 量 内 存 〈 增 加 Nginx 并 发 量 ) ， 又 不 会 使 用 到 磁盘 WO 减少 了 用 户 等 等 啊 应 的 时 间 〉。 








因此 ，upstream 机 制 提供 了 3 种 处 理 包 体 的 方式 ， 不 转发 响应 ( 即 不 实现 反 向 代理 ) 、 转 
发 响应 时 以 下 游 网 速 优先 、 转 发 响应 时 以 上 游 网 速 优 先 。 怎 样 告诉 upstream 机 制 使 用 哪 种 方 
式 处 理 上 游 的 响应 包 体 呢 ? 当 请 求 ngx_http request t 结 构 体 的 subrequest_ in memory 标 志 位 为 1 
时 ， 将 采用 第 1 种 方式 ， 即 不 转发 响应 ， 当 subrequest in_ memory 为 0 时 ， 将 转发 响应 。 而 
ngx http upstream conf {配置 结构 体 中 的 buffering 标 志 位 ， 会 决定 转发 响应 时 是 否 开启 更 多 的 
内 存 和 磁盘 文件 用 于 缓存 上 游 响应 ， 如 果 buffering 为 0， 则 以 下 游 网 速 优先 ， 使 用 固定 大 小 的 
内 存 作为 缓存 ， 如 果 buffering 为 1， 则 以 上 游 网 速 优 先 ， 使 用 更 多 的 内 存 、 硬 盘 文件 作为 组 
存 。 
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1. 不 转发 啊 应 





不 转发 包 体 是 upstream 机 制 最 基本 的 功能 ， 特 别 是 客户 端 请 求 派生 出 的 子 请 求 多 半 不 需 
要 转发 包 体 ，upstream 机 制 的 最 低 目 标 就 是 允许 HTTP 模 块 以 TCP 访 问 上 游 服 务 器 ， 这 时 
HTTP 模 块 仅 希望 解析 包头 、 包 体 ， 没 有 转发 上 游 响应 的 需求 。upstream 机 制 提供 的 解析 包头 
的 回调 方法 是 process_header， 而 解析 包 体 的 回调 方法 则 是 input filter。 在 12.6 节 将 会 描述 这 
种 处 理 包 体 的 最 基本 方式 是 如 何 工作 的 。 








2. 转 及 啊 应 时 下 游 网 速 优 先 





在 转 及 啊 应 时 ， 如 果 下 游 网 速 快 于 上 游 网 速 ， 或 者 它们 速度 相差 不 大 ， 这 时 不 需要 开辟 
大 块 内 存 或 者 磁盘 文件 来 缓存 上 游 的 咽 应 。 我 们 将 在 12.7 市 中 讲述 这 种 处 理 方 式 下 upstream 
机 制 是 如 何 工作 的 。 


3. 转 发 啊 应 时 上 游 网 速 优先 


在 转发 啊 应 时 ， 如 果 上 游 网 速 快 于 下 游 网 速 〈 由 于 Nginx 文 持 蜗 并 发 特性 ， 所 以 大 多 数 
时 候 都 用 于 做 最 前 端的 Web 服 务 器 ， 这 时 上 游 网 速 都 会 快 于 下 游 网 速 ) ， 这 时 需要 开辟 内 存 
或 者 磁盘 文件 缓存 来 自 上 游 服务 器 的 响应 ， 注 意 ， 缓 存 可 能 会 非常 大 。 这 种 处 理 方式 比较 复 


杂 ， 在 12.8 节 中 我 们 会 详细 描述 其 主要 流程 。 
12.5.3 ”接收 啊 应 头 部 的 流程 


下 面 开始 介绍 读 取 上 游 服 务 器 响应 的 ngx_ http upstream process_header 方 法 ， 这 个 方法 主 
要 用 于 接收 、 解 析 响 应 头 部 ， 当 然 ， 由 于 upstream 机 制 是 不 涉及 应 用 层 协议 的 ， 谁 使 用 了 
upstream 谁 就 要 负责 解析 应 用 层 协议 ， 所 以 必须 由 HTTP 横 块 实现 的 process header 方 法 解析 
响应 包头 。 当 包头 接收 、 解 析 完 毕 后 ，ngx http_upstream process_ header 方 法 还 会 决定 以 哪 种 


方式 处 理 包 体 (参见 12.5.2 节 中 介绍 的 3 种 包 体 处 理 方式 ) 。 
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在 接收 响应 包头 的 阶段 中 ， 处 理 连 接 读 事件 的 方法 始终 是 


ngx http_upstream process_header， 也 就 是 说 ， 访 方法 会 反复 被 调用 ， 在 研究 其 流程 时 需要 


别 注 意 。 图 12-5 描 述 了 它 的 主要 流程 。 
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守 


1) 检查 读 事件 





的 有 效 性 
[接收 响应 超时 或 者 还 未 发 送 请 求 给 上 游 ] 


[ 读 事 件 可 用 , 再 检查 buffer 接收 缓冲 区 是 否 可 用 |] 


2) 调 用 ngx_http_upstream_next 





方法 重 试 或 结束 
[ 如果 buffer 缓 冲 区 未 分 配 ] 


缓冲 区 已 分 配 亡 
[缓冲 区 已 分 配 过 ] 3 ) 分 配 buffer 
接收 缓冲 区 


4) 调用 recv 
方法 读 取 缓冲 区 
[检查 recv 返 回 值 ] 


[连接 关闭 






或 者 错误 ] 












[返回 NGX_AGAIN] 





[buffer 绥 冲 区 用 尽 ] 
[返回 NGX_HTTP_UPSTREAM_INVALID_HEADERI] 


[ 读 取 到 响应 ] 


6 ) 调 用 process_header 





方法 解析 响应 包头 
[有 空闲 缓冲 区 ] [检查 process_header 返回 值 ] 


5 ) 将 读 事件 
< 人 [返回 NGX_ERRORI] 添加 到 epoll 中 


[返回 NGX_AGAN 后 ， 上 骨 检 查 buffer 是 否 全 部 用 尽 ] 
[返回 Ncx om 





7) 调 用 ngx_http_upstream_finalize_request 
方法 结束 请 求 










8) 调用 ngx_http_upstream_process_headers 
方法 处 理 headers_in 
[检测 subrequest jin_memory 标志 位 ,确认 是 否 需 要 转发 包 体 ] 


subrequest_in_memory 为 0] 9) 调 用 ngx_http_upstream_send_response 


方法 转发 响应 





[subrequesLin_memory 为 1, 不 转发 啊 应 ] 





10) 初始 化 过 滤 
包 体 的 方法 


[检测 buffer 中 是 否 已 经 接收 到 包 体 ] 
buffer 中 已 含有 包 体 ] 昼 用 input_filter 
方法 处 理 已 接收 到 的 包 体 





[buffer 中 未 含有 包 体 ] 


12) 重新 设置 


read_event_handler 


13) 调用 ngx_http_upstream_process_body_in_memory 


方法 处 理 包 体 





图 12-5 ngx_http_upstream_process_header 方 法 的 流程 图 
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下 面 详细 介绍 图 12-$ 中 的 13 个 步骤 。 








1) 首先 检查 读 事件 是 否 有 效 ， 包 括 检查 timedout 标 志 位 是 否 为 1， 如 果 timedout 为 1， 则 
表示 读 取 啊 应 已 经 超时 ， 这 时 跳 到 第 2 步调 用 ngx http upstream next 方 法 决定 下 一 步 的 动作 ， 
其 中 传递 的 参数 是 NGX HTTP_UPSTREAM FT TIMEOUT。 如 果 timedout 为 0， 则 继续 检查 
request_sent 标 志 位 。 如 果 request_ sent 为 0， 则 表示 还 没有 发 送 请 求 到 上 游 服 务 器 残 收 到 来 自 
上 游 的 响应 ， 不 符合 upstream 的 设计 场景 ， 这 时 仍然 跳 到 第 2 步调 用 ngx_http_upstream_ next 方 
法 ， 传 递 的 参数 是 NGX _ HTTP UPSTREAM FT ERROR。 如 果 读 事件 完全 有 效 ， 则 跳 到 第 3 


步 执行 。 


2) 只 有 请 求 触 发 了 失败 条 件 后 ， 才 会 执行 hgx http_upstream next 方 法 ， 访 方法 将 会 根据 
配置 信息 决定 下 一 步 究 竟 是 重新 发 起 upstream 请 求 ， 还 是 结束 当前 请 求 ， 在 12.9.2 节 会 详细 说 
明 该 方法 的 工作 流程 。 当 前 读 事 件 处 理 完毕 。 














3) 检查 ngx_http_upstream t 结 构 体 中 接收 啊 应 头 部 的 buffer 绥 冲 区 ， 如 果 它 的 start 成 员 指 
同 NULL， 说 明 绥 冲 区 还 未 分 配 内 存 ， 这 时 将 按照 ngx http_upstream conf t 配 置 结构 体 中 的 
buffer size 成 员 指定 的 大 小 来 为 buffer 组 冲 区 分 配 内 存 。 


4) 调用 recv 方 法 在 buffer 绥 冲 区 中 读 取 上 游 服 务 器 发 来 的 响应 。 检 测 recv 方 法 的 返回 
值 ， 有 3 类 返回 值 会 导致 3 种 不 同 的 结果 : 如 果 返 回 NGX_AGAIN， 则 表示 还 需要 继续 接收 响 
应 ， 这 时 跳 到 第 5 步 执行 ， 如 果 返 回 9 (表示 上 游 服 务 器 主动 关闭 连接 ) 或 者 返回 
NGX ERROR， 这 时 跳 到 第 2 步 执行 hgx http upstream next 方法， 传递 的 参数 是 
NGX_HTTP_UPSTREAM FT_ERROR; 如 果 返 回 正 数 ， 这 时 该 数值 表示 接收 到 的 响应 长 度 ， 
跳 到 第 6 步 处 理 啊 应 。 








5) 调用 ngx_handle read_event 方 法 将 读 事件 再 添加 到 epoll 中 ， 等 待 读 事 件 的 下 次 触发 。 
ngx http_upstream process_header 方 法 执行 完毕 。 
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NGX HTTP UPSTREAM INVALID HEADER 表 示 包 头 不 合法 ， 这 时 跳 到 第 2 步调 用 
ngx_http_upstream _ next 方法， 传递 的 参数 是 

NGX _ HTTP UPSTREAM FT INVALID HEADER; 返回 NGX ERROR 表 示 出 现 错 误 ， 直 接 跳 
到 第 7 步 执 行 ， 返回 NGX_OK 表 示 解 析 到 完整 的 包头 ， 这 时 跳 到 第 8 步 执行 ， 返 回 

NGX_ AGAIN 表示 包头 还 没有 接收 完整 ， 这 时 将 检测 buffer 绥 冲 区 是 否 用 尽 ， 如 采 绥 冲 区 已 经 
用 尽 ， 则 说 明 包 头 太 大 了 ， 超 出 了 缓冲 区 人 允许 的 大 小 ， 这 时 跳 到 第 2 步调 用 
ngx_http_upstream next 方法， 传递 的 参数 依然 是 

NGX _ HTTP UPSTREAM FT INVALID HEADER， 其 表示 包头 不 合法 ， 而 如 果 绥 冲 区 还 有 空 
闲 空间， 则 返回 第 4 步 继续 接 收 上 游 服 务 器 的 响应 。 








7) 调用 ngx http_upstream finalize request 方 法 结束 请 求 〈 详 见 12.9.3 节 ) ， 


En 


ngx http_upstream process_header 方 法 执行 完毕 。 


8) 调用 ngx http_upstream process_headers 方 法 处 理 已 经 解析 出 的 头 部 ， 访 方法 将 会 把 已 
经 解析 出 的 头 部 设置 到 请 求 nex http request t 结 构 体 的 headers_out 成 员 中 ， 这 样 在 调用 
ngx_http send_ header 方 法 发 送 啊 应 包头 给 客户 端 时 将 会 发 送 这 些 设 置 了 的 头 部 。 











接 下 来 检查 是 否 需要 转发 响应 ，ngx http_ request tt 结构 体 中 的 subrequest in _ memory 标志 
位 为 1 时 表示 不 需要 转发 啊 应 ， 跳 到 第 10 步 执行 ;subrequest in _ memory 为 0 时 表示 需要 转发 啊 
应 到 客户 端 ， 跳 到 第 9 步 执 行 。 


9) 调用 ngx http_ upstream send _ response 方法 开始 转发 响应 给 客户 端 ， 同 时 


ry 


ngx http_upstream process_ header 方 法 执行 完毕 。 





10) 首先 检查 HTTP 模 块 是 否 实现 了 用 于 人 处理 包 体 的 input_filter 方 法 ， 如 果 没 有 实现 ， 则 
使 用 upstream 定 义 的 默认 方法 ngx http upstream non buffered filter 代 替 input filter， 其 中 
input filter_ctx 将 会 被 设置 为 ngx_http_ request 结构 体 的 指针 。 如 果 用 户 已 经 实现 了 input_filter 
方法 ， 则 表示 用 户 希 望 自己 处 理 包 体 (如 ngx http memcached module 模 块 ) ， 这 时 首先 调用 
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input filter_init 方 法 为 处 理 包 体 做 初始 化 工作 。 


11) 在 第 6 步 的 process_header 方 法 中 ， 如 果 解 析 完 包头 后 绥 冲 区 中 还 有 多 余 的 字符 ， 则 
表示 还 接收 到 了 包 体 ， 这 时 将 调用 input filter 方 法 第 一 次 处 理 接收 到 的 包 体 。 


12) 设置 upstream 的 read event handler 为 ngx http_upstream process_body in memory 方 
法 ， 这 也 表示 再 有 上 游 服 务 器 发 来 啊 应 包 体 ， 将 由 该 方法 来 处 理 (参见 12.6 节 ) 。 


13) 调用 ngx http upstream process body in memory 方 法 开始 处 理 包 体 。 





从 上 面 的 第 12 步 可 以 看 出 ， 当 不 需要 转发 啊 应 时 ， 

ngx_http_upstream process_body in _ memory 方法 将 作为 读 取 上 游 服务 器 包 体 的 回调 方法 。 什 
么 时 候 无 须 转发 包 体 呢 ? 在 subrequest_ in_memory 标 志 位 为 1 时 ， 实 际 上 ， 这 也 意味 着 当前 请 
求 是 个 subrequest 子 请 求 。 也 就 是 次 ， 在 通 凋 情 况 下 ， 如 果 来 目 客户 端的 请 求 直接 使 用 

upstream 机 制 ， 那 都 需要 将 上 游 服务 堪 的 啊 应 直接 转发 给 客户 站， 而 如 果 是 客户 端 请 求 派生 
出 的 子 请 求 ， 则 不 需要 转发 上 游 的 啊 应 。 因 此 ， 当 我 们 开发 HITP 模 块 实现 茶 个 功能 时 ， 知 
再 要 访问 上 游 服务 器 获取 一 些 数据 ， 那 么 可 开发 两 个 HTTP 模 块 ， 第 一 个 HITP 模 块 用 于 处 理 
客户 疹 请 求 ， 当 它 需 要 访问 上 游 服 务 器 时 吏 派 生出 子 请 求 访问 ， 第 二 个 HTTP 模块 则 专用 于 
访问 上 游 服 务 器 ， 在 子 请 求解 析 完 上 游 服务 占 的 啊 应 后 ， 再 沿 活 父 请 求 处 理 客户 端 要 求 的 业 


务 。 




















人 @@ ;i 各 ”以 上 描述 的 开发 场景 是 Nginx 推 荐 用 户 使 用 的 方式 ， 虽 然 可 以 通过 任意 地 修 政 
subrequest 标 志 位 来 更 改 以 上 特性 ， 但 目前 这 种 设计 对 于 分 离 关 注 点 还 是 非常 有 效 的 ， 是 一 种 
很 好 的 设计 模式 ， 如 无 必要 最 好 不 要 更 改 。 





从 上 面 的 第 9 步 可 以 看 出 ， 当 需要 转发 包 体 时 将 调用 ngx_http_upstream send response 方 法 
来 转发 包 体 。ngx_http upstream send response 方 法 将 会 根据 negx http_ upstream conf t 配 置 结构 
体 中 的 buffering 标 志 位 来 决定 是 否 打 开 绥 存 来 处 理 啊 应 ， 也 就 是 说 ，buffering 为 0 时 通常 会 默 


认 下 让， 这 时 实生 在 的 褒 《在 | 将 全 人 的 于 放 扩 br OD owne 

















1， 则 表示 上 游 网 速 更 快 ， 这 时 需要 用 大 量 内 存 、 磁 盘 文件 来 缓存 来 目 上 游 的 啊 应 《在 12.8 


节 中 会 介绍 这 二 法 程 》 8 


NNn httpo://ww linuxorobe. con 





12.6 不 转发 啊 应 时 的 处 理 流 程 


实际 上 ， 这 里 的 不 转发 响应 只 是 不 使 用 upstream 机 制 的 转发 响应 功能 而 已 ， 但 如 果 HTTP 
模块 有 意愿 转发 啊 应 到 下 游 ， 还 是 可 以 通过 input filter 方 法 实现 相关 功能 的 。 





当 请 求 属于 subrequest 子 请 求 ， 且 要 求 在 内 存 中 处 理 包 体 时 在 第 5 章 介绍 过 
ngx_http_subrequest 方 法 ， 通 过 它 派生 子 请 求 时 ， 可 以 将 最 后 一 个 flag 参 数 设置 为 
NGX _ HTTP SUBREQUEST IN_ MEMORY 宏 ， 这 样 就 将 ngx_http request t 结 构 体 中 的 
subrequest_in_ memory 标 志 位 设 为 1 了 〉 ， 就 会 进入 本 节 描 述 的 不 转发 响应 这 个 流程 。 或 者 通 
过 主动 设置 subrequest_ in memory 标志 位 为 1 也 可 以 做 到 ， 当 然 并 不 推荐 这 样 做 。 为 什么 呢 ? 
因为 不 需要 转发 响应 时 的 应 用 场景 通常 如 下 : 业务 需求 导致 需要 综合 上 游 服务 器 的 数据 来 重 
新 构造 发 往 客 户 端的 响应， 如 从 上 游 的 数据 库 或 者 Tomcat 服 务 器 中 获取 用 户 权限 信息 等 。 这 
时 ， 根 据 Nginx 推 荐 的 设计 模式 ， 应 当 由 原始 请 求 处 理 客户 端的 请 求 ， 并 派生 出 子 请 求 访问 
上 游 服 务 器 ， 在 这 种 场景 下 ， 一 般 会 希望 在 内 存 中 解析 上 游 服 务 器 的 响应 。 











@@ 注意 其实 ， 在 内 存 中 处 理 上 游 响应 的 包 体 也 有 两 种 方式 ， 第 一 种 方式 接收 到 全 部 
的 包 体 后 再 开始 处 理 ， 第 二 种 方式 是 每 接收 到 一 部 分 响应 后 就 处 理 这 一 部 分 。 第 一 种 方式 可 
能 浪费 大 量 内 存 用 于 接收 完整 的 响应 包 体 ， 第 二 种 方式 则 会 始终 复 用 同一 块 内 存 缓冲 区 。 
HTTP 模 决 可 以 自由 地 选择 使 用 哪 种 方式 。 


ngx_http_upstream process_body in _ memory 就 是 在 upstream 机 制 不 转发 啊 应 时 ， 作 为 读 事 
件 的 回调 方法 在 内 存 中 处 理 上 游 服务 器 啊 应 包 体 的 。 每 次 与 上 游 的 TCP 连 接 上 有 读 事 件 触 发 
时 ， 它 都 会 被 调用 ，HTTP 模 块 通过 重新 实现 input filter 方 法 来 处 理 包 体 ， 在 12.6.1 节 中 会 讨 
论 如 何 实现 这 个 回调 方法 ， 如 果 HTTP 模 块 不 实现 input filter 方 法， 那么 upstream 机 制 就 会 自 
动 使 用 默认 的 ngx http_ upstream non buffered filter 方 法 来 处 理 包 体 ， 在 12.6.2 节 中 会 讨论 这 个 
默认 的 input_ filter 方法 做 了 些 什 么 ， 在 12.6.3 节 中 将 会 具体 分 析 
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ngx http upstream process_body in _ memory 方法 的 工作 流程 。 


12.6.1 input_filter 方 法 的 设计 


先 来 看 一 下 input filter 回 调 方 法 的 定义 ， 如 下 所 示 。 


ngx int t (*input filter) (void *data, ssize t bytes); 


其 中 ，bytes 参 数 是 本 次 接收 到 的 包 体 长 度 。 而 data 参 数 却 不 是 指向 接收 到 的 包 体 的 ， 它 
实际 上 是 在 启动 upstream 机 制 之 前 ， 所 设置 的 ngx_http_upstream t 结 构 体 中 的 input filter_ctx 成 
员 ， 下 面 看 一 下 它 的 定义 。 





vorLd *input filter ctx; 


它 被 设计 为 可 以 指 问 任意 结构 体 ， 其 实 束 是 用 来 传递 参数 的 。 因 为 在 内 存 中 人 处理 包 体 
时 ， 可 能 需要 一 个 结构 体 作为 上 下 文 存储 状态 、 结 果 等 一 些 信息 ， 这 个 结构 体 必须 在 局 动 
upstream 机 制 前 设置 。 同 时 ， 在 处 理 包 体 前 ， 还 会 调用 一 次 input_filter_init 方 法 HTTP 模块 
如 果 需 要 在 开始 接收 包 体 时 初始 化 变量 ， 痢 会 在 这 个 方法 中 实现 ) ， 下 面 看 一 下 它 的 定义 。 





ngx int t (*input filter init) (void *data); 





data 参 数 意 义 同 上 ， 仍 然 是 input_filter_ctx 成 员 。 


下 面 将 重点 讨论 如 何在 input_filter 方 法 中 处 理 包 体 。 首 先 要 弄 清楚 是 从 哪里 获取 到 本 次 
接收 到 的 上 游 响 应 包 体 。 答 案 是 可 由 ngx_buf {类 型 的 buffer 绥 冲 区 获得 。buffer 缓 冲 区 中 的 last 
成 员 指向 本 次 接收 到 的 包 体 的 起 始 地 址 ， 而 input_ filter 方法 的 bytes 参 数 表 明了 本 次 接收 到 包 
体 的 字 节 数 。 通 过 buffer->last 和 bytes 获 取 到 本 次 接收 到 的 包 体 后 ， 下 面 的 工作 就 是 由 HITP 模 
块 处 理 接收 到 的 包 体 。 


向 外 更 这 三 六 必 利 的 信 后 ” 江 告 iopr yn 








如 果 我 们 需要 反复 使 用 buffer 缓 冲 区 ， 即 buffer 指 向 的 这 块 内 存 需要 复 用 ， 或 者 换 句 话 
说 ， 下 次 接收 到 的 啊 应 将 会 槛 再 buffer 上 刚刚 接收 到 的 啊 应 ， 那 么 input_filter 方 法 和 被 调 用 时 必 
须 处 理 完 buffer 绥 冲 区 中 的 全 部 内 容 ， 这 种 情况 下 不 需要 修改 buffer 绥 冲 区 中 的 成 员 。 妆 再 次 
接收 到 后 续 的 包 体 时 ， 将 会 继续 从 buffer->last 指 向 的 内 存 地 址 处 覆盖 上 次 的 包 体内 容 。 











如 果 我 们 希望 buffer 缓 冲 区 保存 部 分 或 者 全 部 的 包 体 ， 则 需要 进行 针对 性 的 处 理 。 我 们 
知道 ， 在 ngx _buf {表示 的 缓冲 区 中 ，start 和 end 成 员 圈 定 了 绥 冲 区 的 可 用 内 存 ， 这 对 于 buffer 
缓冲 区 来 说 同样 成 立 ，last 成 员 将 指向 接收 到 的 上 游 服 务 器 的 响应 包 体 的 起 始 内 存 地 址 。 
此 ， 自 由 地 移动 last 指 针 就 是 在 改变 buffer 缓 冲 区 。 例 如 ， 如 果 希 望 buffsr 缓 冲 区 存储 全 部 包 体 
内 容 ， 那 么 不 妨 把 last 指 针 向 后 移动 bytes 字 节 (参见 12.6.2 节 〉 ; 如 果 希 望 buffer 缓 冲 区 尽 可 
能 地 接收 包 体 ， 等 缓冲 区 满 后 再 从 头 接收 ， 那 么 可 以 检测 last 指 针 ， 在 last 未 达到 end 指 针 的 
位 置 时 可 以 继续 向 后 移动 ， 直 到 last 到 达 end 指 针 处 ， 在 到 达 end 指 针 后 可 以 把 last 指 针 指 向 
start 成 员 ， 这 样 又 会 重头 复 用 这 块 内 存 了 。 





input filter 的 返回 值 非常 简单 ， 只 要 不 是 返回 NGX ERROR， 就 都 认为 是 成 功 的 ， 当 
然 ， 不 出 错时 最 好 还 是 返回 NGX _ OK。 如 果 返 回 NGX ERROR， 则 请 求 会 结束 ， 参 见 图 12- 


0。 





12.6.2 ”默认 的 input _ filter 方法 


如 果 HTTP 模 块 没 有 实现 input_ filter 方法， 那么 将 使 用 
ngx http_upstream non buffered filter 方 法 作为 input filter， 这 个 默认 的 方法 将 会 试图 在 buffer 
绥 冲 区 中 存放 全 部 的 啊 应 包 体 。 


ngx_http_upstream non buffered _ filter 方法 其 实 很 简单 ， 下 面 直 接 列 出 其 主要 代码 来 分 析 
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static ngx int t ngx http upstream non buffered filter(voidq *data, ssize t bytes) 


{ 





X* 询 交 说 过 ， 
data 参 数 就 是 
ngx _ http upstream 七 结构 体 中 的 
input filter ctx, 当 
HTTP 模 块 未 实现 
input filter 方法 时 ， 
input filter ctx 成 员 会 指向 请 求 的 


ngx http request 七 结构 体 


ngx http request t r = data; 
ngx buf 七 by 

Nox Charn 二 Gly “LL? 

ngx http upstream 七 uy 

u = r->upstream; 


/找到 
out_bufs 链 表 的 末尾 ， 其 中 
Cl 指向 链表 中 最 后 一 个 
ngx chain 七 元 素 的 
next 成 员 ， 所 以 
cl 最 后 一 定 是 
NULL 空 指针 ， 而 
11 指 向 最 后 一 个 缓冲 区 的 地 址 ， 它 用 来 在 后 面 的 代码 中 向 


out bufs 链 表 添 加 新 的 缓冲 区 


£0or (CE = U=20Ut bufsyp .11 = &u=>0ut bufsy cir C1 = C=2next) 
{ 
11 = &cl->next; 


上 
free bufs 指 向 空闲 的 


ngx_buf 七 结构 体 构成 的 链表 ， 如 果 


free_bufs 此 时 是 空 的 ， 那 么 将 会 重新 由 
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上 ->pool 内 存 池 中 分 配 一 个 


ngx_buf 七 结构 体 给 


cl; 如 果 


free_bufs 链 表 不 为 空 ， 则 直接 由 


free bufs 中 获取 一 个 


ngx_buf 七 结构 体 给 


GL*]/ 
cl = ngx chain get free buf(r->pool, &u->free bufs); 
if (cl == NULL) { 
return NGX ERROR; 








} 
// 将 新 分 配 的 


ngx_buf 七 结构 体 添 加 到 


out _ bufs 链 表 的 末尾 


11 = cil; 
/修改 新 分 配 缓冲 区 的 标志 位 ， 表 明 在 内 存 中 ， 


ELush 标 志 位 为 可 能 发 送 缓冲 区 到 客户 端 服务 ， 参 见 
12 .7 节 


BA 
cl->buf->flush = 
cl->buf->memory = 1; 
// Dietez 基 者 昌 直 时 半 二 村 肛 下 二 民 水 全 大庆 包 体 的 缓冲 区 


b= &u->buffer; 
// last 实 际 指向 本 次 接收 到 的 包 体 首 地 址 


cl->buf->pos = b->last; 
// last 向 后 移动 


bytes 字 节 ， 意 味 着 


buffer 需 要 保存 这 次 收 到 的 包 体 


b->last += bytes; 
// last 和 


pos 成 员 确 定 了 
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cl->buf->last = b->last; 
cl->buf->tag = u->output.tag; 
/* 如 果 没 有 设置 包 体 长 度 ， 


Uu->length 就 是 


NGX MAX SIZE T VALUE， 那么 到 这 里 结束 











if (u->length == NGX MAX SIZE T VALUE 
return NGX OR; 








一 


// 更 新 


length， 需 要 接收 到 的 包 体 长 度 减 少 


bytes 字 节 


u->length -= bytes; 
return NGX OK; 
} 





可 以 看 到 ， 默 认 的 input filter 方 法 会 试图 让 独立 的 buffer 绥 冲 区 保存 全 部 的 包 体 ， 这 就 要 
求 我 们 对 上 游 服务 器 的 啊 应 包 体 大 小 有 绝对 正确 的 判断 ， 否 则 一 旦 上 游 服务 器 发 来 的 响应 包 
体 超过 buffer 绥 冲 区 的 大 小 ， 请 求 将 会 出 错 。 


er 注意 “对 于 上 述 这 段 代 码 的 理解 ， 可 参见 图 12-8 第 4 步 中 nogx_chain_update_chains 方 法 
的 执行 过 程 ， 它 们 是 配对 执行 的 。 


12.6.3 ”接收 包 体 的 流程 


本 节 介 绍 的 实际 就 是 negx http upstream process body in _ memory 方法 的 执行 流程 ， 它 会 
负责 接收 上 游 服务 器 的 包 体 ， 同 时 调用 HTTP 模 块 实现 的 input_filter 方 法 处 理 包 体 ， 如 图 12-6 
所 示 。 


下 面 分 析 图 12-6， 了 解 一 下 在 内 存 中 处 理 包 体 的 流程 。 


1) 和 后 六 yin 人 ODE eth 











志 位 。 如 果 timedout 为 1， 则 表示 读 取 啊 应 超时 ， 这 时 跳 到 第 2 步调 用 
ngx_http_upstream finalize request 方 法 结束 请 求 ， 传 递 的 参数 是 NGX ETIMEDOUT 〈 详 见 
12.9.3 节 ) ; 如 果 timedout 为 0， 则 继续 执行 第 3 步 。 


2) 调用 ngx http _ upstream finalize request 方 法 结束 请 求 ， 该 方法 类 似 于 
ngx_http_finalize_request 方 法 ， 它 们 都 震 要 一 个 rc 参数 ， 来 决定 该 方法 的 行为 。 





3) 在 保存 着 响应 包 体 的 buffer 绥 冲 区 中 ，1last 成 员 指 向 空 闪 内 存 块 的 地 址 (下 次 还 会 由 
last 处 开始 接收 啊 应 包 体 ) ， 而 end 成 员 指 向 缓冲 区 的 结尾 ， 用 end-last 即 可 计算 出 剩余 空 用 内 
存 。 如 果 绥 冲 区 全 部 用 尽 ， 则 跳 到 第 2 步调 用 ngx_http_upstream finalize_request 方 法 结束 请 
求 ， 如 果 还 有 空闲 缓冲 区 ， 则 跳 到 第 4 步 接收 包 体 。 


4) 调用 recv 方 法 接收 上 游 服务 器 的 响应 ， 接 收 到 的 内 容 存 放 在 buffer 缓 冲 区 的 last 成 员 指 
向 的 内 存 中 。 检 查 recv 的 返回 值 ， 不 同 的 返回 值 会 导致 3 种 结果 : 如 果 返 回 NGX_AGAIN， 则 
表示 期 竺 下 一 次 的 读 事件 ， 这 时 跳 到 第 6 步 执行 ， 如 果 返 回 NGX_ERROR 或 者 上 洲 服务 器 主 
动 关闭 连接 ， 则 路 到 第 2 步 结束 请 求 ， 如 果 返 回 正 数 ， 则 表示 接收 到 的 响应 长 度 ， 这 时 跳 到 
第 5 步 处 理 包 体 。 


5) 调用 HTTP 模 块 实现 的 input filter 方 法 处 理 本 次 接收 到 的 包 体 。 检 测 input filter 方 法 的 
返回 值 ， 返 回 NGX_ ERROR 时 跳 到 第 2 步 结束 请 求 。 否 则 ， 再 检测 读 事件 的 ready 标 志 位 ， 如 
果 ready 为 1， 则 表示 仍 有 TCP 流 可 以 读 取 ， 这 时 跳 到 第 3 步 执行 ， 如 果 ready 为 0， 则 跳 到 第 6 


步 执行 。 
6) 调用 ngx handle read_event 方 法 将 读 事件 添加 到 epoll 中 。 


7) 调用 ngx_add_ timer 方 法 将 读 事 件 添加 到 定时 器 中 ， 超 时 时 间 为 
ngx_http_upstream_conf t 配 置 结构 体 中 的 read_timeout 成 员 。 





在 内 存 中 处 理 包 体 的 关键 在 于 如 何 实现 input filter 方 法 ， 特 别 是 在 该 方法 中 对 buffer 绥 冲 
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区 的 管理 。 如 果 上 游 服务 器 的 啊 应 包 体 非 第 小 ， 可 以 考虑 本 节 说 明 的 这 种 方式 ， 它 的 效率 很 


、 


[= 
[BJ] 。 
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1) 检查 读 事件 
是 否 超 时 
[检查 读 事 件 的 timedout 标 志 位 ] 





[timedout 为 1] 


[timedout 为 0] 
















3) 计算 剩余 空 
闲 缓冲 区 
[buffer 中 是 否 还 有 空闲 缓冲 区 ] 

[buffer 组 冲 区 用 尽 ] 


[buffer 绥 冲 区 还 有 空闲 空间 ] 





林 硬 用 Fe 万 法 误区 下 汰 服务 
发 来 的 包 体 
[检测 recv 返 回 值 | 


[ 套 接 字 上 仍 有 流 可 读 ] [出 错 或 者 上 游 服务 器 关闭 了 连接 ] 


[接收 到 包 体 ] 


[返回 NGX_AGAIN] 5 ) 调 用 input filter 
方法 处 理 本 次 接收 的 包 体 
[检测 inputfilter 返 回 值 和 连接 是 否 仍 然 可 读 ] 
人 [input filter 返 回 NGX_ FRROR] 


[ 套 接 字 上 没有 流 可 读 ] 


2) 调 用 ngx_http_upstream_finalize_request 





方法 结束 请 求 


6) 将 读 事 件 
添加 到 epoll 中 


7) 将 读 事件 添加 到 
定时 器 中 





图 12-6 ”ngx_http_upstream_process_body_in_memory 方 法 的 流程 图 
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12.7 以 下 游 网 速 优先 来 转发 啊 应 





转发 上 游 服务 器 的 响应 到 下 游客 户 端 ， 这 项 工作 必然 是 由 上 游 事件 来 驱动 的 。 因 此 ， 以 
下 游 网 速 优先 实际 上 只 是 意味 着 需要 开辟 一 块 固定 长 度 的 内 存 作为 缓冲 区 。 在 图 12-5 的 第 9 
步 中 会 调用 ngx_http_upstream send_response 方 法 向 客户 端 转发 响应 ， 在 该 方法 中 将 会 判断 
buffering 标 志 位 ， 如 果 buffering 为 1， 则 表明 需要 打开 缓冲 区 ， 这 时 将 会 优先 考虑 上 游 网 速 ， 
尽 可 能 多 地 接收 上 游 服务 器 的 响应 到 内 存 或 者 磁盘 文件 中 ;而 如 果 buffering 为 0%， 则 只 开辟 固 
定 大 小 的 缓冲 区 内 存 ， 在 接收 上 游 服务 器 的 响应 时 如 果 绥 冲 区 已 满 则 和 暂停 接收 ， 等 待 缓冲 区 
中 的 响应 发 送 给 客户 端 后 缓冲 区 会 自然 清空 ， 于 是 就 可 以 继续 接收 上 游 服务 器 的 响应 了 。 这 
种 设计 的 好 处 是 没有 使 用 大 量 内 存 ， 这 对 提高 并 发 连接 是 有 好 处 的 ， 同 时 也 没有 使 用 磁盘 文 
件 ， 这 对 降低 服务 器 负载 、 某 些 情况 下 提高 请 求 处 理 能 力也 是 有 益 的 。 


























本 市 我 们 讨论 的 正 是 buffering 标 志 位 为 0 时 的 转发 啊 应 方式 ， 事 实 上 ， 这 时 使 用 的 缓冲 区 
也 是 接收 上 游 服 务 器 头 部 时 所 用 的 内 存 ， 其 大 小 由 ngx http upstream conf t 配 置 结构 体 中 的 
buffer size 配 置 指定 。 


@ 注意 ”buffering 标 志 位 的 值 其 实 可 以 根据 上 游 服务 器 的 响应 头 部 而 改变 。 在 12.1.3 节 
中 我 们 介绍 过 change_buffering 标 志 位 ， 当 它 的 值 为 1 时 ， 如 果 process_header 方 法 解析 出 又- 
Accel-Buffering 头 部 并 设置 到 headers_in 结 构 体 中 后 ， 将 根据 该 头 部 的 值 改 变 buffering 标 志 位 。 
当 X-Accel-Buffering 头 部 值 为 es 时， 对 于 本 次 请 求 而 言 ，buffering 相 当 于 重 设 为 1， 如 果 头 部 
值 为 no， 则 相当 于 buffering 改 为 0， 除 此 以 外 的 头 部 值 将 不 产生 作用 (参见 
ngx_http_upstream_process_buffering 方 法 ) 。 因 此 ， 转 发 响应 时 究竟 是 否 需要 打开 缓存 ， 可 以 
在 运行 时 根据 请 求 的 不 同 而 灵活 变换 。 


12.7.1 转发 啊 应 的 包头 
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转发 响应 包头 这 一 动作 是 在 ngx http_upstream send response 方 法 中 完成 的 ， 无 论 
buffering 标 志 位 是 否 为 0， 都 会 使 用 该 方法 来 发 送 响应 的 包头 ， 图 12-7 和 图 12-9 共 同 构成 了 
ngx_http_upstream_send_response 方 法 的 完整 流程 。 先 来 看 一 下 图 12-7， 它 描述 了 单一 缓冲 区 
下 是 如 何 转发 包头 到 客户 端 ， 以 及 为 转发 包 体 做 准备 的 。 





因为 转 及 啊 应 包头 这 一 过 程 并 不 存在 反复 调用 的 问题 ， 所 以 图 12-7 中 主要 完成 了 两 项 工 
作 : 将 12.5 节 中 解析 出 的 包头 发 送 给 下 游 的 客户 端 、 设 置 转 发 包 体 的 处 理 方法 。 下 面 详 细 解 


释 图 12-7 描 述 的 11 个 步骤 。 


1 ) 调用 ngx_http_send_ header 方 法 癌 下 游 的 客户 端 发 送 HTTP 包头。 在 接收 上 游 服务 器 的 
啊 应 包头 时 ， 在 图 12-5$ 的 第 6 步 中 ，HTTP 模 块 会 通过 process_header 方 法 解析 包头 ， 并 将 解析 
出 的 值 设 置 到 ngx http_upstream t 结 构 体 的 headers_ in 成 员 中 ， 而 在 第 8 步 中 ， 
ngx http upstream process_headers 方 法 则 会 把 headers_ in 中 的 头 部 设置 到 将 要 发 送 给 客户 端的 
headers_out 结 构 体 中 ，ngx_http_send header 方 法 就 是 用 来 把 这 些 包 头发 送 给 客户 端的 。 这 一 
步 同时 会 将 header sent 标 志 位 置 为 1 (header sent 标 志 位 在 12.4 节 中 发 送 请 求 到 上 游 服 务 器 时 
会 使 用 ) 。 
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1 ) 调用 ngx_http_send_header 





方法 回 客 户 端 发 送 HTTP 包 头 
[检查 来 自 客户 端的 HTTP 请 求 包 体 ] 





[客户 端 请 求 的 包 体 保 存在 了 临时 文件 中 ] 





[客户 端的 请 求 没有 包 体 
或 者 包 体 没有 保存 在 临 文件 中 ] 


2 ) 调 用 ngx_pool_run_cleanup_file 
方法 清理 存放 请 求 包 体 的 文件 


[HTTP 模 块 是 否 实 现 input_filter 方 法 ] 













[已 经 实现 了 input_filter 方 法 ] 


[HTTP 模块 没有 实现 input_filter 方 法 ] 











3 ) 用 upstream 
提供 的 默认 方法 设置 nput_filter 







4) 设置 读 事件 处 理 方法 


read_event handler 





5 ) 设 置 写 事件 处 理 方法 


write_event_handler 


6 ) 调 用 input_filter_init 方法 
[检查 缓冲 区 中 是 和 否 已 经 接收 到 包 体 ] 
人 [缓冲 区 中 已 经 含有 包 体 ] 


[ 绥 冲 区 中 没有 接收 到 包 体 ] 


7) 调 用 input__filter 









方法 处 理 本 次 接收 到 的 响应 包 体 





9 ) 清空 buffer 
接收 缓冲 区 





8) 调 用 ngx_http_upstream_process_non_ 





buffered_downstream 方 法 





10) 调 用 ngx_http_send _special 
方法 


与 上 游 服务 器 的 套 接 字 





[检测 三 
[ 套 接 字 上 没有 可 读 内 容 ] 


[ 套 接 字 上 有 可 读 内 容 ] 


11) 调用 ngx_htt p_upstream_process_non_ 
buffered_upstream 方 法 
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图 12-7 buffering 标 志 位 为 0 时 发 送 响应 包头 的 流程 


2) 如 果 客 户 端的 请 求 中 有 HTTP 包 体 ， 而 且 曾 经 调用 过 11.8.1 节 中 的 
ngx_http read client request body 方 法 接收 HTTP 包 体 并 把 包 体 存放 在 了 临时 文件 中 ， 这 时 就 
会 调用 ngx_pool_run_cleanup file 方 法 清理 临时 文件 。 为 什么 要 在 这 一 步 清理 临时 文件 呢 ? 
为 上 游 服务 器 发 送 响应 时 可 能 会 使 用 到 临时 文件 ， 之 后 收 到 响应 解析 响应 包头 时 也 不 可 以 清 
理 临 时 文件 ， 而 一 旦 开始 向 下 游客 户 端 转发 HTTP 响 应 时 ， 则 意味 着 肯定 不 会 再 需要 客户 端 
请 求 的 包 体 了 ， 这 时 可 以 关闭 、 转 移 或 者 删除 临时 文件 ， 具 体 动作 由 HTTP 模 块 实现 的 hander 
回调 方法 决定 。 














3) 如 果 HTTP 模 块 没有 实现 过 滤 包 体 的 input filter 方 法 ， 则 再 把 12.6.2 节 介绍 过 的 默认 的 
ngx_http_upstream non buffered_filter 方 法 作为 处 理 包 体 的 方法 ， 它 的 工作 就 在 于 使 用 out_bufs 
链表 指 问 接收 到 的 buffer 绥 冲 区 内 容 。 在 12.7.2 节 中 将 会 综合 介绍 它 的 作用 。 








4) 设置 读 取 上 游 服务 器 响应 的 方法 为 ngx http_ upstream process_ non buffered upstream， 
即 设置 upstream 中 的 read_event handler 回 调 方法 ， 这 样 ， 当 上 游 服 务 堪 接收 到 啊 应 时 ， 通 过 
ngx http upstream handler 方 法 可 最 终 调用 ngx http_ upstream process_non buffered_upstream 来 
接收 啊 应 。 


5) 将 ngx http upstream process_non buffered downstream 设 置 为 向 下 游客 户 端 发 送 包 体 
的 方法 ， 也 就 是 把 请 求 ngx_http request t 中 的 write_event handler 设 置 为 这 个 方法 ， 这 样 ， 
且 TCP 连 接 上 可 以 同 下 游客 户 端 发 送 数据 时 ， 会 通过 ngx http handler 方 法 最 终 调用 到 
ngx_http upstream process_non buffered downstream 来 发 送 响应 包 体 。 


6) 调用 HTTP 模 块 实现 的 input_ filter_init 方 法 〈 当 HTTP 模 块 没 有 实现 input _ filter 方法 时 ， 
是 默认 任何 事情 也 不 做 的 ngx http_upstream non buffered filter init 方 法 ) ， 为 input filter 方 
法 处 理 包 体 做 初始 化 准备 。 


的 人 下 全 喜人 关 后 是 下 红 且 纯 类 天 半生 做 二 站 洛 was 








缓冲 区 中 的 last 指 针 是 人 否 等 于 pos 指 针 ) 。 如 果 已 经 接收 到 包 体 ， 则 跳 到 第 7 步 执行 ， 如 果 没 
有 接收 到 包 体 ， 则 跳 到 第 9 步 执 行 。 


7) 调用 input filter 方 法 处 理 包 体 。 


8) 调用 ngx http upstream process_non buffered downstream 方 法 把 本 次 接收 到 的 包 体 向 
下 游客 户 端 发 送 。 








9) 将 buffer 缓 冲 区 清空 ， 其 实 就 是 执行 下 面 两 行 语句: 





u->buffer.pos = u->buffer.start; 
u->buffer.last = u->buffer.start; 





pos 指 针 一 般 指向 未 经 处 理 的 啊 应 ， 而 last 指 针 一 般 指 向 刚 接 收 到 的 啊 应 ， 这 时 把 它们 全 
部 设 为 指 癌 绥 冲 区 起 始 地 址 的 start 指 针 ， 即 表示 清空 缓冲 区 。 





10) 调用 ngx http_ send special 方 法 ， 如 下 所 示 。 








if (ngx http send speciall(r, NGX HTTP FLUSH) == NGX ERROR) { 
ngx http upstream finalize request(r, u, 0); 
eturny 


} 





NGX_HTTP_FLUSH 标 志 位 意味 着 如 果 请 求 r 的 out 绥 冲 区 中 依然 有 每 待 发 送 的 响应 ， 
则 “催促 ”着 发 送出 它们 。 








11) 如 果 与 上 游 服 务 器 的 连接 上 有 可 读 事 件 ， 则 调用 
ngx http_upstream process_non buffered upstream 方 法 处 理 啊 应 ; 否则 ， 当 前 流程 结束 ， 将 控 


制 权 交还 给 Nginx 框 架 。 


以 上 步骤 提 到 的 下 游 处 理 方 法 ngx http_upstream process_non buffered downstream 和 上 游 
处 理 方法 ngx http_upstream process_non buffered_upstream 都 将 在 下 文中 介绍 。 
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12.7.2 ”转发 啊 应 的 包 体 


当 接 收 到 上 游 服务 器 的 啊 应 时 ， 将 会 由 ngx http_ upstream process_non buffered upstream 
方法 处 理 连接 上 的 这 个 读 事件 ， 该 方法 比较 简单 ， 下 面 直接 列举 源 代 码 说 明 其 流程 。 





static void ngx http upstream process non buffered upstream(ngx http request t r, ngx http upstream t u) 
{ 
ngx connection 七 *c; 


// 获取 


Nginx 与 上 游 服务 器 间 的 


TCP 连 接 





C = u->peer.connection; 


// 如 果 读 取 响 应 超时 (超时 时 间 为 


read timeout) ， 则 需要 结束 请 求 


if (c->read->timedout) { 
// ngx http upstream finalize request 方 法 可 参见 


L293 


ngx http upstream finalize request(r, u, 0); 
return; 
} 
/* 这 个 方法 才 是 真正 决定 以 固定 内 存 块 作为 缓存 时 如 何 转 发 响应 的 ， 注 意 ， 传 递 的 第 


2 个 参数 是 


0#y 
ngx http upstream process non buffered request (r, 0); 


} 





可 以 看 到 ， 实 际 接收 上 游 服 务 器 响应 的 其 实 是 
ngx_http_upstream process_non buffered_request 方 法 ， 先 不 着 急 看 它 的 实现 ， 先 来 看 看 癌 下 游 
客户 端 发 送 啊 应 时 调用 的 ngx http_upstream process_non buffered downstream 方 法 是 怎样 实现 
的 ， 如 下 上 所 示 。 











static void ngx http upstream process non buffered downstream(ngx http redquest 七 r) 
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ngx connection 七 cy 
ngx http upstream t u; 
// 注意 ， 这 个 


Nginx 与 客户 端 之 间 的 


TCP 连 接 


C = r->connection; 
Uu = r->upstream; 
WeV = CcC->write; 


/* 如 果 发 送 超 时 ， 那 么 同样 要 结束 请 求 ， 超 时 时 间 就 是 


nginx.conf 文 件 中 的 


sendq timeout 配 置 项 


G4 
if (wev->timedout) { 
c->timedout = 1; 
// 注意 ， 结 束 请 求 时 传递 的 参数 是 








NGX_ HTTP REQUEST TIME OUT 
ngx http upstream finalize request(r, u, NGX HTTP REQUEST TIME OUT); 
return; 


























} 
// 同样 调用 该 方法 向 客户 端 发 送 响 应 包 体 ， 注 意 ， 传 递 的 第 


2 个 参数 是 


ngx http upstream process non buffered request(r, 1); 





无 论 是 接收 上 游 服务 器 的 响应 ， 还 是 向 下 游客 户 端 发 送 响 应 ， 最 终 调用 的 方法 都 是 
ngx http_upstream process_non buffered request， 唯 一 的 区 别 是 该 方法 的 第 2 个 参数 不 同 ， 当 
需要 读 取 上 游 的 响应 时 传递 的 是 0， 当 需要 向 下 游 发 送 响应 时 传递 的 是 1。 下 面 先 看 看 该 方法 
到 底 做 了 哪些 事情 ， 如 图 12-8 所 示 。 


图 12-8 中 的 do_write 变 量 就 是 ngx http upstream process_non buffered request 方 法 中 的 第 2 
个 参数 ， 当 然 ， 首 先 它 还 会 有 一 个 初始 化 ， 如 下 所 示 。 





do write = do write || u->length == 0; 
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这 里 的 length 变 量 表示 还 需要 接收 的 上 游 包 体 的 长 度 ， 当 length 为 0 时 ， 说 明 不 再 需要 接 
收 上 游 的 啊 应 ， 那 只 能 继续 向 下 游 发 送 啊 应 ， 因 此 ，do_write 只 能 为 1。do_write 标 志 位 表示 
本 次 是 否 向 下 游 发 送 响应 。 下 面 详 细 解 释 图 12-8 中 的 每 个 步 又。 


1) 如 果 do_write 标 志 位 为 1， 则 跳 到 第 2 步 开 始 同 下 游 发 送 啊 应 ; 如 果 do_write 为 0， 则 
表示 需要 由 上 游 读 取 啊 应 ， 这 时 跳 到 第 6 步 执 行 。 注 意 ， 在 图 12-8 中 ， 这 一 步 是 在 一 个 大 循 
环 中 执行 的 ， 也 就 是 说 ， 与 上 、 下 游 间 的 通信 可 能 反复 执行 。 














2) 首先 检查 缓存 中 来 自 上 游 的 响应 包 体 ， 是 否 还 有 未 转发 给 下 游 的 。 这 个 检查 过 程 很 
简单 ， 因 为 每 当 在 缓冲 区 中 接收 到 上 游 的 响应 时 ， 都 会 调用 input_filter 方 法 来 处 理 。 当 HTTP 
模块 没有 实现 该 方法 时 ， 我 们 就 会 使 用 12.6.2 节 介绍 过 的 ngx_ http upstream non buffered filter 
方法 来 处 理 响 应 ， 该 方法 会 在 out bufs 链 表 中 增加 ngx_buf tt 缓冲 区 〈 没 有 分 配 实际 的 内 存 ) 
指向 puffer 中 接收 到 的 响应 。 因 此 ， 在 向 下 游 发 送 包 体 时 ， 直 接 发 送 out_ bu& 绥 冲 区 指向 的 内 
容 即 可 ， 每 当 发 送 成 功 时 则 会 在 下 面 的 第 4 步 中 更 新 out buf 缓冲 区 ， 从 而 将 已 经 发 送出 去 的 
ngx_buf t 成 员 回 收 到 free_bufs 链 表 中 。 














事实 上 ， 检 查 是 否 有 内 容 需 要 转发 给 下 游 的 代码 是 这 样 的 ; 








if, (u=>0ut bufs || u=->busy bufs) { 


} 





可 能 有 人 会 奇怪 ， 为 什么 除了 out_ buf 缓冲 区 链表 以 外 还 要 检查 busy bufgs 呢 ? 这 是 因为 
在 第 3 步 向 下 游 发 送 out buf 指向 的 响应 时 ， 未 必 可 以 一 次 发 送 完 。 这 时 ， 在 第 4 步 中 ， 会 使 
用 busy bufs 指 向 out bu& 中 的 内 容 ， 同 时 将 out bufs 置 为 空 ， 使 得 它 在 继续 处 理 接收 到 的 响应 
包 体 的 ngx_http_upstream non buffered filter 方 法 中 指 疝 新 收 到 的 响应 。 因 此 ， 只 有 out_bufs 和 
busy buf 链表 都 为 空 时 ， 才 表示 没有 响应 需要 转发 到 下 游 ， 这 时 跳 到 第 5 步 执行 ， 否 则 跳 到 
第 2 步 向 下 游 发 送 响应 。 
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3) 调用 ngx http output filter 方 法 同 下 游 发 送 out_bufs 指 问 的 内 容 ， 其 代码 如 下 。 





rc = ngx http output filter(r, u->out bufs); 
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2) 检测 发 送 缓 汪 区 
是 否 有 内 容 
[检查 out bufs 或 者 busy_bufs 链表 是 否 为 空 ] 





































1 ) 结合 length 成 员 和 do_write 
人 参数 重 置 do_write 


[outbufs 或 者 busy_bufs 不 为 空 ] 
示 志 位 为 ]] 
[两 链表 和 皆 


3 ) 幸 用 ngx_ http_output_filter 
方法 发 送 包 体 


[检测 do write 标志 位 ] | 


do write 


指向 NULL] 





4) 调 用 ngx_chain_update_chains 


位 为 0 
me 方法 更新 组 种 区 链 丢 


[do_write 标志 











S) 更 新 buffer 
缓冲 区 中 的 pos、 last 


6) 检测 buffer 
缓冲 区 的 空闲 空间 长 度 
[检查 空闲 空间 长 度 是 否 为 0, 以 及 读 事 件 的 ready 标 志 位 ] 


[buffer 还 有 空闲 空间 , 且 ready 标志 位 为 1] 














7) 调 用 recy 
方法 接收 响应 
[ 检测 recv 返 回 值 ] 





[buffer 绥 冲 区 用 尽 , 或 ready 为 0] 


[ 读 取 到 响应 包 体 ] [未 读 取 到 响应 包 体 ] 
[返回 NGX_AGAIN] 
8 ) 调 用 input_filter 
方法 处 理 包 体 


En 
11) 将 下 游 写 事 件 添 加 到 
定时 器 中 


12) 将 上 游 读 事件 添加 到 
:poll 











13) 将 上 游 恋 事件 添加 到 


半生 秋 轧 和 和 和 人 仆 门 Peto /7 | 1 nuxpr obe. con 





图 12-8 ngx_http_upstream_process_non_buffered_request 方 法 的 流程 图 





读者 在 这 里 可 能 会 有 疑问 ， 在 busy buf 不 为 空 时 ， 不 是 也 有 内 容 要 发 送 吗 ? 注意 ， 
busy bufs 指 向 的 是 上 一 次 ngx http_output filter 未 发 送 完 的 缓存 ， 这 时 请 求 ngx_http request t 绪 
构 体 中 的 ou 缓冲 区 已 经 保存 了 它 的 内 容 ， 不 需要 再 次 发 送 busy_bufs 了 。 





4) 调用 ngx_chain update_chains 方 法 更 新 上 文 说 过 的 free_bufs、busy_bufs、out_bufs 这 3 个 
缓冲 区 链表 ， 它 们 实际 上 做 了 以 下 3 件 事情 。 





. 清空 out_bufs 链 表 。 


: 把 out_bufs 中 已 经 发 送 完 的 ngx_buf t 结 构 体 清空 重 置 ( 即 把 pos 和 last 成 员 指 向 statt) ， 
同时 把 它们 追加 到 free_bufs 链 表 中 。 


如 果 out_bufs 中 还 有 未 发 送 完 的 ngx_buf t 结 构 体 ， 那 么 添加 到 busy_bufs 链 表 中 。 这 一 


步 与 ngx_http_upstream_non_buffered_filtet 方 法 的 执行 是 对 应 的 。 


5) 当 busy buf 链表 为 空 时 ， 表 示 到 目前 为 止 需要 向 下 游 转 发 的 响应 包 体 都 已 经 全 部 发 
送 完 了 〈( 也 就 是 说 ，ngx_http_request t 结 构 体 中 的 ou 缓冲 区 都 发 送 完 了 ) ， 这 时 将 把 buffer 接 
收 缓冲 区 清空 (pos 和 1last 成 员 指向 start) ， 这 样 ，buffer 接 收 缓冲 区 中 的 内 容 释 放 后 ， 才 能 继 
续 接 收 更 多 的 啊 应 包 体 。 


6) 获取 buffer 绥 冲 区 中 还 有 多 少 剩余 空间 ， 即 : 





size = u->buffer.end - u->buffer.1last; 





这 里 获取 的 size 就 是 第 7 步 rfecv 方 法 能 够 接收 的 最 大 字 节 数 。 





当 size 大 于 0， 且 与 上 游 的 连接 上 确实 有 可 读 事件 时 〈 检 查 读 事件 的 ready 标 志 位 ) ， 就 
会 跳 到 第 7 步 开始 接收 响应 ， 否 则 直接 跳 到 10 步 准备 结束 本 次 调度 中 的 转发 动作 。 
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7) 调用 recv 方 法 将 上 游 的 响应 接收 到 buffsr 缓 冲 区 中 。 检 查 recv 的 返回 值 ， 如 果 返 
数 ， 则 表示 确实 接收 到 响应 ， 跳 到 第 8 步 处 理 接收 到 的 包 体 ， 如 果 返 回 NGX_AGAIN， 则 表 
示 期 待 epoll 下 次 有 读 事件 时 再 继续 调度 ， 这 时 路 到 第 10 步 执行 ， 如 果 返 回 0， 则 表示 上 游 服 
务 器 关闭 了 连接 ， 跳 到 第 9 步 执 行 。 





8) 调用 input filter 方 法 处 理 包 体 〈 参 考 12.6.2 节 的 默认 处 理 方 法 ) 。 


9) 执行 到 这 一 步 表示 该 取 到 了 来 目 上 游 的 啊 应 ， 这 时 设置 do_write 标 志 位 为 1]， 同 时 跳 
到 第 1 步 准 备 向 下 游 转发 刚 收 到 的 啊 应 。 


10) 调用 ngx handle write event 方 法 将 Nginx 与 下 游 之 间 连 接 上 的 写 事件 添加 到 epoll 中 。 


11) 调用 ngx add timer 方 法 将 Nginx 与 下 游 之 间 连 接 上 的 写 事件 添加 到 定时 右 中 ， 超 时 时 
间 就 是 配置 文件 中 的 send_ timeout 配 置 项 。 


12) 调用 ngx_handle_read event 方 法 将 Nginx 与 上 游 服 务 器 之 间 的 连接 上 的 读 事件 添加 到 
epoll 中 。 


13) 调用 ngx_ add_timer 方 法 将 Nginx 与 上 游 服 务 器 之 间 连 接 上 的 读 事件 添加 到 定时 器 
中 ， 超 时 时 间 就 是 ngx_http upstream conf t 配 置 结构 体 中 的 read timeout 成 员 。 





阅读 完 第 11 章 ， 读 者 应 该 很 熟悉 Nginx 读 / 写 事 件 的 处 理 过 程 了 。 另 外 ， 理 解 转 发 包 体 这 
一 过 程 最 关键 的 是 弄 清 楚 缓冲 区 的 用 法 ， 特 别 是 分 配 了 实际 内 存 的 buffer 缓 冲 区 与 仅仅 负责 
指向 buffer 组 冲 区 内 容 的 3 个 链表 〈out buf&、busy bufs、free bufs) 之 间 的 关系 ， 这 样 就 对 这 
种 转发 过 程 的 优 缺 点 非常 清楚 了 。 如 果 下 游 网 速 慢 ， 那 么 有 限 的 buffer 缓 冲 区 就 会 降低 上 游 
的 发 送 响应 速度 ， 可 能 对 上 游 服务 器 带 来 高 并 发 压力 。 
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12.8 ”以 上 游 网 速 优先 来 转 及 啊 应 





如 果 上 游 服 务 器 向 Nginx 发 送 响应 的 速度 远 快 于 下 游客 户 端 接收 Nginx 转 发 响应 时 的 速 
度 ， 这 时 可 以 通过 将 ngx http_upstream conf t 配 置 结构 体 中 的 buffering 标 志 位 设 为 1!1， 人 允许 
upstream 机 制 打 开 更 大 的 缓冲 区 来 缓存 那些 来 不 及 向 下 游 转 发 的 响应 ， 人 允许 当 达 到 内 存 构成 
的 缓冲 区 上 限时 以 磁盘 文件 的 形式 来 缓存 来 不 及 向 下 游 转 发 的 响应 。 什 么 是 更 大 的 缓冲 区 
呢 ? 由 12.7 节 我 们 知道 ， 当 buffering 标 志 位 为 0 时 ， 将 使 用 ngx http_upstream conf t 配 置 结构 体 
中 的 buffer_size 指 定 的 一 块 固定 大 小 的 缓冲 区 来 转发 啊 应 ， 而 当 buffering 为 1 时 ， 则 使 用 bufs 成 
员 指 定 的 内 存 缓冲 区 (最 多 拥有 bufs.num 个 ， 每 个 缓冲 区 大 小 固定 为 bufs.size 字 节 ) 来 转发 响 
应 ， 当 上 游 响 应 占 满 所 有 缓冲 区 时 ， 使 用 最 大 不 超过 max_ temp_file_size 字 节 的 临时 文件 来 组 
存 响应 。 








事实 上 ， 官 方 发 布 的 ngx_http_proxy module 反 向 代理 模块 默认 配置 下 就 是 使 用 这 种 方式 
来 转发 上 游 服务 器 响应 的 ， 由 于 它 涉及 了 多 个 内 存 缓冲 区 的 配合 问题 ， 以 及 临时 磁盘 文件 的 
使 用 ， 导 致 它 的 实现 方式 异常 复杂 ，12.8.1 节 介绍 的 ngx_event_pipe t 结 构 体 是 该 转发 方式 的 
核心 结构 体 ， 需 要 基于 它 来 理解 转发 流程 。 














这 种 转发 啊 应 方式 集成 了 Nginx 的 文件 缓存 功能 ， 本 节 将 只 讨论 纯粹 转发 啊 应 的 流程 ， 
不 会 涉及 文件 缓存 部 分 (以 临时 文件 缓存 啊 应 并 不 属于 文件 缓存 ， 因 为 临时 文件 在 请 求 结 
后 会 被 删除 ) 。 








12.8.1 ngx event pipe t 结 构 体 的 意义 


如 有 果 将 ngx_http_upstream conf {配置 结构 体 的 buffering 标 志 位 设置 为 1， 那 么 
ngx_event_pipe_t 结 构 体 必须 要 由 HTTP 模 块 创建 。 


TT ne 





自动 实例 化 ， 因 此 ， 必 须 由 使 用 upstream 的 HTTP 模 块 为 pipe 分 配 内 存 。 





ngx_event_pipe 结构 体 维护 着 上 下 游 间 转发 的 响应 包 体 ， 它 相当 复杂 。 例 如 ， 缓 冲 区 链 
表 ngx_chain t 类 型 的 成 员 就 定义 了 6 个 (包括 free raw_bufs、in、out、free、busy、 
preread_bufs)， 为 什么 要 用 如 此 复杂 的 数据 结构 支撑 看 似 简 单 的 转发 过 程 呢 ? 这 是 因为 
Nginx 的 宗旨 就 是 高 效率 ， 所 以 它 绝 不 会 把 相同 内 容 复制 到 两 块 内 存 中 ， 而 同一 块 内 存 如 果 
既 要 用 于 接收 上 游 发 来 的 响应 ， 又 要 准备 向 下 游 发 送 ， 很 可 能 还 要 准备 写 入 临时 文件 中 ， 这 
就 带 来 了 很 高 的 复杂 度 ，ngx_event pipe t 结 构 体 的 任务 就 在 于 解决 这 个 问题 。 

















理解 这 个 结构 体 中 各 个 成 员 的 舍 义 将 会 帮助 我 们 弄 消 楚 buffering 为 1 时 转发 啊 应 的 流程 ， 
特别 是 可 以 错 清 楚 Nginx 绝 不 复制 重复 内 存 的 局 效 做 法 是 如 何 实现 的 。 当 然 ， 我 们 也 可 以 先 
跳 到 12.8.2 放 综合 理解 这 种 转发 方式 下 的 运行 机 制 ， 再 针对 流程 中 过 到 的 ngx_event_pipe_t 结 
构 体 中 的 成 员 返 回 到 本 市 来 伍 询 其 意义 。 下 面 看 一 下 它 各 个 成 员 的 意义 。 











typedef struct ngx event pipe s ngx event pipe t; 


// 处 理 接收 自 上 游 的 包 体 的 回调 方法 原型 





typedef ngx int t (*ngx event pipe input filter pt) (ngx event pipe t p, ngx buf t buf); 
// 向 下 游 发 送 响 应 的 回调 方法 原型 





typedef ngx int t (*ngx event pipe output filter pt) (void data, ngx chain t chain); 
struct ngx event pipe s { 
// Nginx 与 上 游 服务 器 间 的 连接 





ngx connection t *upstream; 


// Nginx 与 下 游客 户 端 间 的 连接 


ngx connection 七 *downstream; 


/* 直 接 接 收 自 上 游 服务 器 的 缓冲 区 链表 ， 注 意 ， 这 个 链表 中 的 顺序 是 逆序 的 ， 也 就 是 说 ， 链 表 前 端的 


ngx_buf 七 缓冲 区 指向 的 是 后 接收 到 的 响应 ， 而 后 端的 


ngx_buf 七 缓冲 区 指向 的 是 先 接收 到 的 响应 。 因 此 ， 





free_raw_ bufs 链 表 仅 在 接收 响应 时 使 用 


/ 


ngx chain t free raw bufs; 


TP http: /ww | i nuxporobe. con 








in 链表 是 在 


input _ filter 方法 中 设置 的 ， 可 参考 


ngx event pipe copy input _ filter 方法 ， 它 会 将 接收 到 的 缓冲 区 设置 到 





in 链表 中 


ngx chain t in; 


// 指向 刚刚 接收 到 的 一 个 缓冲 区 


ngx chain 七 **]ast_ in; 


/x 保 存 着 将 要 发 送 给 客户 端的 缓冲 区 链表 。 在 写 入 临时 文件 成 功 时 ， 会 把 
in 链表 中 写 入 文件 的 缓冲 区 添加 到 


out 链 表 中 


ngx chain t out; 


// 指向 刚 加 入 


out 链 表 的 缓冲 区 ， 暂 无 实际 意义 


ngx chain 七 **]ast out; 


// 等 待 释放 的 缓冲 区 


ngx chain t free; 


/设置 
busy 缓 冲 区 中 待 发 送 的 响应 长 度 触 发 值 ， 当 达到 
busy_size 长 度 时 ， 必 须 等 待 
busy 缓 冲 区 发 送 了 足够 的 内 容 ， 才 能 继续 发 送 
out 和 


in 缓冲 区 中 的 内 容 


Ssize t busy size; 


表示 上 次 调用 
ngx_http_output filter 方法 发 送 响 应 时 没有 发 送 完 的 缓冲 区 链表 。 这 个 链表 中 的 缓冲 区 已 经 保存 到 请 求 的 


out 链 表 中 ， 
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busy 仅 用 于 记录 还 有 多 大 的 响应 正 等 待 发 送 


ngx chain t busy; 


/* 处 理 接收 到 的 来 自 上 游 服 务 器 的 缓冲 区 。 一 般 使 用 


upstream 机 制 默认 提供 的 


ngx event pipe copy input filter 方 法 作为 





input filter*/ 
ngx event pipe input filter pt input filter; 
/用 可 





input filter 方法 的 成 员 ， 一 般 将 它 设置 为 


ngx_http request 七 结构 体 的 地 址 


void input ctx; 


/* 表 示 向 下 游 发 送 响 应 的 方法 ， 默 认 使 用 


ngx http output filter 方 法 作为 


output filter*/ 
ngx event pipe output filter pt output filter; 
// 指向 





ngx http request 七 结构 体 


void *output ctx; 


// 标志 位 ， 
read 为 


1 时 表示 当前 已 经 读 取 到 上 游 的 响应 


unsigned read:1; 


/* 标 志 位 ， 为 
1 时 表示 启用 文件 缓存 。 本 章 描 述 的 场景 都 忽略 了 文件 缓存 ， 也 就 是 默认 
cacheable 值 为 


Oy 
unsigned cacheable:1; 
// 标志 位 ， 为 


1 时 表示 接收 上 游 响应 时 一 次 只 能 接收 一 个 


ngx_buf 七 缓冲 区 


口 岂 日 所 有 有 和 所 掉 由 http' /wNv inuxorobe. con 





unsigned single buf:1; 


/* 标 志 位 ， 为 


1 时 一 旦 不 再 接收 上 游 响 应 包 体 ， 将 尽 可 能 地 立刻 释放 缓冲 区 。 所 谓 尽 可 能 是 指 ， 一 旦 这 个 缓冲 区 没有 被 引用 ， 如 没有 用 于 写 入 临时 文件 或 者 用 于 向 - 


Pool 内 存 池 


unsigned free bufs:1; 


提供 给 


HTTP 模 块 在 


input filter 方 法 中 使 用 的 标志 位 ， 表 示 


Nginx 与 上 游 间 的 交互 已 结束 。 如 果 


HTTP 模 块 在 解析 包 体 时 ， 认 为 从 业务 上 需要 结束 与 上 游 间 的 连接 ， 那 么 可 以 把 


upstream done 标 志 位 置 为 


1*/ 
unsigned upstream done:1; 
/*Nginx 与 上 游 服务 器 之 间 的 连接 出 现 错误 时 ， 


upstream error 标 志 位 为 


1， 一 般 当 接收 上 游 响 应 超时 ， 或 者 调用 


recv 接 收 出 现 错误 时 ， 就 会 把 该 标志 位 置 为 


1*/ 
unsigned upstream error:1; 


/* 表 示 与 上 游 的 连接 状态 。 当 


Nginx 与 上 游 的 连接 已 经 关闭 时 ， 


upstream eof 标志 位 为 


1*/ 
unsigned upstream eof:1; 


/* 表 示 暂 时 阻塞 住 读 取 上 游 响应 的 流程 ， 期 待 通过 向 下 游 发 送 响应 来 清理 出 空闲 的 缓冲 区 ， 再 用 空 出 的 缓冲 区 接收 响应 。 也 就 是 说 ， 


upstream blocked 标 志 位 为 


1 时 会 在 


ngx event pipe 方 法 的 循环 中 先 调用 





ngx event pipe write to downstream 方 法 发 送 响 应 ， 然 后 再 次 调用 


"qe FEET http: // waw | inuxorobe. con 








xy 
unsigned upstream blocked:1; 
// downstream done 标 志 位 为 


1 时 表示 与 下 游 间 的 交互 已 经 结束 ， 目 前 无 意义 


unsigned downstream done:1; 


/*Nginx 与 下 游客 户 端 间 的 连接 出 现 错误 时 ， 


downstream error 标志 位 为 


1。 在 代码 中 ， 一 般 是 向 下 游 发 送 响 应 超时 ， 或 者 使 用 


ngx_http output filter 方 法 发 送 响应 却 返回 





NGX_ERROR 时 ， 把 
downstream error 标志 位 设 为 


1*/ 
unsigned downstream error:1; 
/* cyclic temp file 标 志 位 为 


1 时 会 试图 复 用 临时 文件 中 曾经 使 用 过 的 空间 。 不 建议 将 
cyclic temp file 设 为 

1。 它 是 由 

ngx_http_upstream conf t 配 置 结构 体 中 的 同名 成 员 赋 值 的 


*/ 
unsigned cyclic temp file:1; 
// 表示 已 经 分 配 的 缓冲 区 数目 ， 


alLlocatedq 受 到 


bufs .num 成 员 的 限制 


ngx_int t allocated; 


/xbufs 记 录 了 接收 上 游 响应 的 内 存 缓 冲 区 大 小 ， 其 中 
bufs .size 表 示 每 个 内 存 缓 冲 区 的 大 小 ， 而 
bufs .num 表 示 最 多 可 以 有 


num 个 接收 缓冲 区 


全 革 直 PP 及 站 由 由 Ptto: /ww inuxorobe. con 





// 用 于 设置 、 比 较 缓 冲 区 链表 中 


ngx _ buf 七 结构 体 的 


tag 标 志 位 


ngx buf tag 七 tag; 
// 已 经 接收 到 的 上 游 响应 包 体 长 度 


off t read length; 
/* 与 


ngx http upstream conf t 配 置 结构 体 中 的 


max _ temp file size 含 义 相 同 ， 同 时 它们 的 值 也 是 相等 的 ， 表 示 临 时 文件 的 最 大 长 度 


off t max temp file size; 


与 





ngx http upstream conf t 配 置 结构 体 中 的 





temp_file write_ size 含义 相同 ， 同 时 它们 的 值 也 是 相等 的 ， 表 示 一 次 写 入 文件 时 的 最 大 长 度 


WA 





ssize 七 temp file write size; 


// 读 取 上 游 响应 的 超时 时 间 








ngx msec t read timeout; 


// 向 下 游 发 送 响 应 的 超时 时 间 





ngx msec t send timeout; 


// 向 下 游 发 送 响 应 时 ， 
TCP 连 接 中 设置 的 


send lowat “水位” 


ssize t send lowat; 


// 用 于 分 配 内 存 缓冲 区 的 连接 池 对 象 


ngx Pool 七 *pool; 
// 用 于 记录 上 日志 的 


ngx 1og 七 对 象 


ngx log 七 *1og7 
// 表示 在 接收 上 游 服务 器 响应 头 部 阶段 ， 已 经 读 取 到 的 响应 包 体 
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ngx chain t *preread bufs; 


// 表示 在 接收 上 游 服务 器 响应 头 部 阶段 ， 已 经 读 取 到 的 响应 包 体 长 度 


size t preread size; 


// 仅 用 于 缓存 文件 的 场景 ， 本 章 不 涉及 ， 故 不 再 详 述 该 缓冲 区 


ngx buf 七 *buf to file; 
// 存放 上 游 响应 的 临时 文件 ， 最 大 长 度 由 





max temp file size 成 员 限 制 





ngx temp fil 
// 已 使 用 的 


t, *temp: filey 


ngx buf 七 缓冲 区 数目 


int num; 


}; 





注意 ，ngx_event pipe _t 结 构 体 仅 用 于 转发 啊 应 。 





12.8.2 ”转发 啊 应 的 包头 





开始 转发 响应 也 是 通过 ngx_http_ upstream send response 方 法 执行 的 。 图 12-9 展 示 了 转发 响应 包头 和 初始 化 ngx_event 
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1) 调用 ngx_http_send_header 


方法 向 客户 端 发 送 HTTP 包 头 
[检查 来 自 客户 端的 HTTP 请 求 包 体 ] 








[ 请 求 没有 包 体 
[客户 端 请 求 的 包 体 保存 在 了 临时 文件 中 ] 或 者 和 钵 没有 保存 在 售 曾 文件 中 | 


2 ) 调 用 ngx_pool_run_ cleanup_file 





方法 清理 文件 


3) 初始 化 ngx_event_pipe_t 
结构 体 


4) 初 始 化 预 读 缓冲 
区 链表 


5) 设置 上 游 读 事件 处 理 方法 


read_event handler 


6 ) 设 置 下 游 写 事件 处 理 方法 


write_event handler 


gy) 调 用 ngx_http _upstream_process_upstream 


方法 处 理 上 游 啊 应 


@ 


图 12-9 ”buffering 标 志 位 为 0 时 转发 响应 包头 的 流程 图 





下 面 说 明 一 下 图 12-9 中 的 步 又 。 
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1) 首先 调用 ngx_http_send_header 方 法 问 下 游客 户 端 发 送 ngx_http_ request_t 结 构 体 的 headers_out 中 设置 过 的 HITP 响 上 


2) 如 果 客 户 端 请 求 中 存在 HTTP 包 体 ， 而 且 包 体 已 经 保存 到 | 





备 时 文件 中 了 ， 这 时 将 会 调用 ngx pool run_cleanup_fike” 


3) ngx_http_upstream t 结 构 体 中 的 pipe 成 员 并 不 是 在 这 一 步 中 创建 ， 它 仅 在 这 一 步 中 初始 化 部 分 成 员 ， 因 此 , 一 旦 p 


// 注意 ， 这 里 是 直接 引用 必须 分 配 过 内 存 的 


pipe 指 针 


ngx event pipe t* P 


六 = u->pipe; 
/* 设 置 向 下 游客 户 端 发 送 响 应 的 方法 为 


ngx http output filter, 该 方法 在 第 


Pp->output filter = (ngx event pipe output filter pt) ngx http output filter; 





output_ctx 指 向 当 前 请 求 的 


ngx_http_request t 结 构 体 ， 这 是 因为 接 下 来 转发 包 体 的 方法 都 只 接受 





ngx event pipe t 参 数 ， 且 只 能 由 
output ctx 成 员 获 取 到 表示 请 求 的 
ngx_http_ request t 结 构 体 

*/ 


Pp->output ctx = r; 


// 设置 转发 响应 时 启用 的 每 个 缓冲 区 的 
tag 标 志 位 


P->tag = u->output.tag; 


// pufs 指 定 了 内 存 缓冲 区 的 限制 


p->bufs = u->conf->bufas 


// 设置 


busy 缓 冲 区 中 待 发 送 的 响应 长 度 触发 值 


p->busy size = u->conf->busy buffers size; 


// upstream 在 这 里 被 初始 化 为 


Nginx 与 上 游 服 务 器 之 间 的 连接 


p->upstream = u->peer.connection; 


x downstream 在 这 里 被 初 始 化 为 


Nginx 与 下 游 客户 端 之 间 的 连接 


p->downstream = C7 





pr [| 站 http:/ /Ww |1 nNUxorobe. con 





p->pool = r->pool; 


// 初始 化 记录 日 志 的 


log 成 员 


p->1l0g = C->1og7 


// 设置 临时 存放 上 游 响 应 的 单个 缓存 文件 的 最 大 长 度 


p->max temp file size = u->conf->max temp file size; 


// 设置 一 次 写 入 文件 时 写 入 的 最 大 长 度 


p->temp file write size = u->conf->temp file write size; 


// 以 当前 


location 下 的 配置 来 设置 读 取 上 游 响 应 的 超时 时 间 


p->read timeout = u->conf->read timeout; 


// 以 当前 


location 下 的 配置 来 设置 发 送 到 下 游 的 超时 时 间 


p->send timeout = clcf->send timeout; 


// 设置 向 客户 端 发 送 响 应 时 
TCP 中 的 


send_ lowat “永福 


p->send lowat = clcf->send lowat; 











4) 初始 化 preread_bufs 预 读 缓 冲 区 链表 《所谓 预 读 ， 就 是 在 读 取 包头 时 也 预先 读 取 到 了 部 分 包 体 ) ， 注 意 ， 


p->preread bufs->buf = &u->buffer; 
p>preread bufs—>next = NULL; 
p->preread size = u->buffer.last - u->buffer.pos; 





实际 上 就 是 把 preread_bufs 中 的 缓冲 区 指向 存放 头 部 的 buffer 缓 冲 区 ， 在 图 12-11 中 的 第 1 步 会 介绍 它 的 用 法 。 


5) 设置 处 理 上 游 读 事件 回调 方法 为 ngx http_upstream process_Upstream。 


6) 设置 处 理 下 游 写 事件 的 回调 方法 为 ngx_http_upstream process_downstream。 





7) 调用 ngx_http_upstream process_upstream 方 法 处 理 上 游 发 来 的 响应 包 体 。 
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ngx_event_pipe_t 结 构 体 是 打开 绥 存 转发 响应 的 关键 ,下面 的 章节 中 我 们 会 一 直 与 它 “ 打 交道 ”。 





12.8.3 ”转发 啊 应 的 包 体 




















在 图 12-9 中 我 们 看 到 ， 处 理 上 游 读 事件 的 方法 是 ngx_http_upstream process_upstream， 处 理 下 游 写 事件 的 方法 是 ngx | 





ngx int t ngx event pipe(ngx event pipe t *p, ngx int t do write) 




















其 中 ，p 参 数 正 是 负责 转发 响应 的 ngx_event_pipe_t 结 构 体 ， 而 do_write 则 是 标志 位 ， 其 为 1 时 表示 需要 向 下 游客 户 端 % 


下 面 介绍 图 12-10 中 的 10 个 步 又 。 





1) 检查 do_write 标 志 位 ， 如 果 do_write 为 0， 则 直接 跳 到 第 5 步 开始 读 取 上 游 服务 器 发 来 的 响应 ; 如 果 do_write 为 1， 贝 





2) 调用 ngx_event pipe_write_to_downstream 方 法 (参见 12.8.5 节 ) 向 下 游客 户 端 发 送 响 应 包 体 ， 检 测 其 返回 值 : 如 果 
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1 ) 检测 do write 
标志 位 













[do_write 标 志 位 为 1] [do write 标志 位 为 0] 


) 调用 ngxevent_pipe_write to_downstream 


方法 向 下 游 发 送 响应 
[检查 方法 返回 值 ] 


’ 


[返回 NGX_OK] [返回 NGX_BUSY] 


[返回 NGCGX_ABORT ] 


5 ) 调 用 ngx_event_pipe_read_upstream 


方法 由 上 游 读 取 响应 
[检查 方法 返回 值 ] 





[返回 NGX_ABORT] 


3) 返 回 
NGX_ABORT 


[返回 NCX OK] [没有 可 读 内 容 ] 
6) 设 置 do write 
标志 位 为 1 


7 a PF eR 


8) 将 下 六 与 于 什 深 加 天 


9 ) 将 人 NGX_OK 










10) 将 Lh : 六 
生生 tp: // WW | 1 NUXor obe,. con 





图 12-10 ngx_event_bipe 方 法 的 流程 图 




















3) ngx_event pipe 方 法 结束 ， 返 回 NGX _ABORT 表 示 请 求 处 理 失 败 。 











4 


Wea 





ngx_event pipe 方 法 结束 ， 返 回 NGX OK 表示 本 次 暂 不 往 下 执行 。 








Wa 


5) 调用 ngx_event_pipe_read_upstream 方 法 (参见 12.8.4 节 ) 读 取 上 游 服务 器 的 响应 ， 同 时 检测 其 返回 值 以 及 ngx_evel 











Na 


6) 设置 do_write 标 志 位 为 1， 继 续 跳 到 第 1 步 向 下 游 发送 刚 收 到 的 上 游 响应 ， 重 复 这 个 循环 。 





Wa 


7) 调用 ngx_handle_read_event 方 法 将 上 游 的 读 事 件 添加 到 epoll 中 ， 等 待 下 一 次 接收 到 上 游 响应 的 事件 出 现 。 





WA 


8) 调用 ngx_add timer 方 法 将 上 游 的 读 事件 添加 到 定时 器 中 ， 超 时 时 间 就 是 ngx_event_pipe_t 结 构 体 的 read_timeout 成 5 


A 


9 





调用 ngx_handle_write_event 方 法 将 下 游 的 写 事件 添加 到 epoll 中 ， 等 待 下 一 次 可 以 向 下 游 发 送 响 应 的 事件 出 现 。 











10) 调用 ngx_add timer 方 法 将 下 游 的 写 事件 添 加 到 定时 器 中 ， 超 时 时 间 就 是 ngx_event_pipe_t 结 构 体 的 send_timeout 成 





可 以 看 到 ，ngx_event_ pipe 方法 在 没有 涉及 缓存 细节 的 情况 下 设计 了 转发 响应 的 流程 ， 它 是 通过 调用 ngx_event pipe__ 





12.8.4 ngx event pipe read_upstream 方 法 




















oe 


ngx_event_pipe_read_upstream 方 法 负责 接收 上 游 的 啊 应 ， 在 这 个 过 程 中 会 涉及 以 下 4 种 情况 。 








* 接收 响应 头 部 时 可 能 接收 到 部 分 包 体 。 
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. 如 果 没 有 达到 bufsnum 上 限 ， 那 么 可 以 分 配 bufs.size 大 小 的 内 存 块 充当 接收 缓冲 区 。 


如 果 恰 好 下 游 的 连接 处 于 可 写 状 态 ， 则 应 该 优先 发 送 响应 来 清理 出 空闲 缓冲 区 。 


如 果 缓 冲 区 全 部 写 满 ， 则 应 该 写 入 临时 文件 。 





这 4 种 情况 会 造成 ngx_event pipe_read_upstream 方 法 较为 复杂 ， 特 别 是 任何 一 个 ngx_buf {t 组 冲 区 都 存在 复 用 的 情况 ， 
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[检查 preread_bufs 预 读 绥 冲 区 链表 指针 是 否 为 空 ] 







[preread_bufs 不 为 空 


[preread_bufs 为 空 , 检查 free_raw_bufs 链 表 指 针 是 否 为 空 


1 ) 准备 处 理 preread_bufs 
中 存放 包 体 的 缓冲 区 





[free_raw bufs 不 为 空 





[free_rawbufs 为 空 , 检查 allocated 是 否 小 于 bufs.num] 
2) 使 用 free_ raw_bufs 
接收 上 游 啊 应 





[已 分 配 组 冲 区 数目 allocated 小 于 bufs.num | 


[allocated 大 于 或 等 于 bufs. num , 检查 是 和 否 可 向 下 游 发 送 啊 应 ] 
3 ) 分 配 新 的 缓冲 区 
接收 上 游 啊 应 







[Nginx 与 下 游 的 连接 上 可 写 事 件 已 经 准备 好 ] 
[下 游 写 事件 不 可 用 , 检查 临时 文件 是 否 


达到 max_temp_file _size] 
4 )upstream_blocked 标 志 位 置 为 1， 
返回 NGX_OK 





[临时 缓存 文件 未 达到 上 限 ] 


5) 将 上 游 响 应 写 信 
临时 文件 









[临时 文件 大 小 已 达到 限制 ] 





6) 调用 recv_chain 
方法 接收 上 游 响 应 包 体 






da Aa 
free_raw bufs 链表 未 





名 


图 12-11 使 用 缓冲 区 接收 上 游 响应 的 流程 图 
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图 12-11 中 的 步骤 很 清晰 ， 主 要 是 在 寻找 使 用 哪 一 块 缓冲 区 接收 上 游 啊 应 。 注 意 ， 在 选择 缓冲 区 时 也 有 优先 级 。 下 面 


















































1) 首先 检查 ngx_event_pipe_ t 结 构 体 中 的 preread_bufs 绥 冲 























区 〈 若 无 特 殊 说 明 ， 以 下 介绍 的 成 员 都 属于 ngx_event_ pipe 





2) 检查 free_ raw_bufs 缓 冲 区 链表 ，free_raw_bufs 用 来 表示 一 次 ngx_event pipe_read upstream 方 法 调用 过 程 中 接收 到 | 








3) 将 已 经 分 配 的 缓冲 区 数量 〈allocated 成 员 ) 与 bufks.num 配 置 相 比 ， 如 果 allocated 小 于 bufs.num， 则 可 以 从 pool 内 存 污 























4) 检查 Nginx 与 下 游 的 连接 downstream 成 员 ， 检 查 它 的 写 事件 的 ready 标 志 位 ， 如 果 ready 为 1!1， 则 表示 当前 可 以 向 下 























5) 检查 临时 文件 中 已 经 写 入 的 响应 内 容 长 度 〈 也 就 是 temp_fle->offset) 是否 达到 配置 上 限 〈( 也 就 是 max temp file s 


6) 调用 recv_chain 方 法 接收 上 游 的 响应 。 





7) 将 新 接收 到 的 缓冲 区 置 到 free_raw_bufs 链 表 的 最 后 。 




















图 12-11 中 的 这 7 个 步骤 将 会 找 出 一 个 缓冲 区 接收 上 游 的 响应 ， 并 把 这 个 缓冲 区 添加 到 free_raw_bufs 链 表 中 ， 下 面 我 

















图 12-12 展 示 了 ngx_event_pipe_read_upstream 方 法 的 全 部 流程 ， 其 中 主要 包括 一 个 接收 上 游 啊 应 的 循环 ， 而 每 一 次 接 ! 
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1) 检查 上 游 连接 是 否 结束 ， 
或 者 暂 无 可 读 内 容 





取 上 游 响应 ] 





结束 , 或 者 暂 不 可 读 ] 


[upstream 









2) 使 用 缓冲 区 读 
取 上 游 啊 应 


[上 游 关 闭 连 接 ] 


[有 需要 处 理 的 读 取 到 的 响应 | 





3) 置 read 


7 园 .、 返回 NGX_AGAIN 
标志 位 为 1 












4 各 现行 外 更 浊 让 区 全 有 个 的 
noex_Dut_t 


8) 置 upstream_eof 为 1 





表示 上 游 连接 结束 
[直接 返回 NGX_OK ] 
5 ) 调 用 ngx_event_pipe_remove_ 


shadow_links 方 法 






















[检查 读 取 到 的 内 容 是 否 全 者 9 检 春 上 上 游 连 接 
保存 在 当前 缓冲 区 中 1 是 否 关闭 





[ 读 取 到 的 内 容 小 于 当前 缓冲 区 大 小 ] 
[ 读 取 到 的 内 容 大 于 或 等 于 当前 缓冲 区 的 大 小 <> 
[上 游 连 接 关 闭 ] 
6) 调用 inputfilter 
方法 处 理 包 体 10) 调用 input_filter 
方法 处 理 包 体 


7) 将 free_raw_bufs [检查 free_bufs 标志 位 ] 


指向 剩余 缓冲 区 
[上 游 连接 未 关闭 ] 


[free_bufs 为 1 ] 
[free_bufs 为 0] 
11) 释放 缓冲 区 
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图 12-12 ngx_event_pipe_read_upstream 方 法 接收 上 游 响 应 的 流程 








1) 检查 上 游 连接 是 否 结束 ， 以 及 与 上 游 连接 的 读 事 件 是 否 已 经 就 绪 ， 代 码 如 下 。 








ji 得 
3 个 标志 位 的 意义 可 参见 
地 .和 .1 节 ， 其 中 竹 一 个 为 


1 都 表示 上 游 连接 需要 结束 


if (p->upstream eof || p->upstream error || p->upstream done) { 


// 跳 到 第 


break; 


/如 果 读 事件 的 

ready 标 志 位 为 

0， 则 说 明 没有 上 游 响 应 可 以 接收 ; 

prereaa_bufs 预 读 缓冲 区 为 空 ， 表 示 接收 包头 时 没有 收 到 包 体 ， 或 者 收 到 过 包 体 但 已 经 处 理 过 了 


*/ 
if (p->preread bufs == NULL && !p->upstream->read->ready) { 


// 跳 到 第 


9 步 执行 


break; 











如 果 这 两 个 条 件 有 一 个 满足 ， 则 需要 跳 到 第 9 步 ， 准 备 结束 ngx_event_pipe_read_upstream 方 法 ， 否 则 继续 执行 第 2 步 。 











2) 接收 上 游 响 应 ， 这 一 步 实际 上 就 是 执行 图 12-11 中 列 出 的 7 个 步骤 。 它 会 导致 3 种 结果 : (如 果 free_raw_bufs 链 表 





3) 置 read 标 志 位 为 1， 表 示 接 收 到 的 包 体 待 处 班 





[FF 
O 


4) 从 接收 到 的 缓冲 区 链表 中 取出 一 块 ngx_buf tt 缓冲 区 。 





上 | 人 下 "EB 太 由 shadow 本 条 ux ober COP 区 ， 必 











6) 检查 本 次 读 取 到 的 包 体 是 否 大 于 或 等 于 缓冲 区 的 剩余 空间 大 小 。 这 一 步 的 意义 在 于 ， 如 果 当 前 接收 到 的 长 度 小 3 





7) 将 本 次 接收 到 的 缓冲 区 添加 到 free_raw_bufs 链 表 末 尾 ， 继 续 第 1 步 执行 这 个 大 循环 。 





8) 将 upstream_ eof 标志 位 置 为 1， 表 示 上 游 服 务 器 已 经 关闭 了 连接 。 





9) 检查 upstream_eof 和 upstream_error 标 志 位 是 否 有 任意 一 个 为 1， 如 果 有 ， 则 说 明 上 游 连接 已 经 结束 ， 这 时 如 果 free 


























10) 再 次 调用 input fitter 方 法 处 理 free_raw_bufBs 中 的 缓冲 区 〈 类 似 第 6 步 ， 但 这 次 只 处 理 可 能 剩余 的 最 后 一 个 缓冲 区 ) 























11) 检查 free_bufs 标 志 位 ， 如 果 free_bufs 为 1， 则 说 明 需 要 尽快 释放 缓冲 区 中 用 到 的 内 存 ， 这 时 调用 ngx_pfree 方 法 释 





可 以 看 到 ，ngx_event_pipe_read_upstream 方 法 将 会 把 接收 到 的 响应 存放 到 内 存 或 者 磁盘 文件 中 ， 同 时 用 ngx_buf t 绥 ? 








12.8.5 ngx event pipe write to downstream 方 法 




















ngx event pipe write to_ downstream 方 法 负责 把 in 链 表 和 out 链 表 中 管理 的 缓冲 区 发 送 给 下 游客 户 端 ， 因 为 out 链 表 中 和 








下 面 详细 分 析 一 下 图 12-13 中 的 13 个 步骤 。 








1) 首先 检查 上 游 连接 是 否 结束 ， 判 断 依据 与 图 12-12 中 的 第 1 步 非 常 相 似 ， 检 查 upstream eof、upstream error 还 有 ups 














2) 调用 output fiter 方 法 把 out 链 表 中 的 缓冲 区 发 送 到 下 游客 户 端 。 





3) 调用 output filter 方法 把 ip 链表 中 的 缓冲 区 发 送 到 下 游客 户 端 。 
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4) 将 downstream_done 标 志 位 置 为 1 (目前 没有 任何 意义 ) ，ngx_event_pipe_write_to_downstream 方 法 结束 。 




















5) 计算 busy 缓 冲 区 中 待 发 送 的 响应 长 度 ， 检 查 它 是 否 超过 busy size 配置， 如 果 其 大 于 或 等 于 busy_size， 则 跳 到 第 10; 














6) 首先 检查 out 链 表 是 否 为 空 ， 如 果 out 中 有 内 容 ， 那 么 立刻 跳 到 第 7 步 准备 发 送 out 缓 冲 区 中 的 响应 ， 如 果 out 为 空 ，; 









































7) 取出 out 链 表 首 部 的 第 一 个 ngx_buf it 绥 冲 区 ， 检 查 待 发 送 的 长 度 加 上 这 个 缓冲 区 后 是 否 已 经 超过 busy_size 配 置 ， 妇 
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Wi 





[上 游 连接 已 经 结束 


[上 游 连 接 未 结束 ] 











[ 写 事 件 准备 好 ] 


S ) 计 算 busy 
缓冲 区 大 小 


2) 疝 下 洲 发 送 
out 绥 冲 区 . 


3) 问 下 洲 发 送 
in 缓冲 区 











[busy 绥 冲 区 未 超过 busy_sizel 





4) 设 置 


首 downstream_down 


标志 位 为 1 







6) 检 测 out 和 in 
缓冲 区 链表 





[busy 缓冲 区 超 ; 过 busy _sizel| 


[in 链表 不 为 空 ] 
[in、out 链表 为 空 
或 竺 发送 内 容 超 过 


busy_size] 










| out 链表 不 为 空 ] 


7) 使 用 out 链表 首 个 绥 冲 区 . 
作为 发 送 内 容 
[ 写 事 件 未 准备 好 ] 


自 7 
缓冲 区 作 为 发 送 内 容 





9) 将 刚 处 理 的 buf 
设置 到 out 链 表 


10) 检查 out 组 冲 区 以 及 之 前 各 步 又 
= 内容 需要 发 送 













[没有 需要 发 送 的 内 容 ] 
[有 内 容 需 要 发 送 ] 


11) 调 用 output_filter 
发 送 啊 应 


12) 调 用 ngx_ chain_update_chains 
方法 更 新 缓冲 区 


13) 释 放 free 
is 冲 区 


中 让 和 加 和 tt p: / /wwwTinioxbe. con 





图 12-13 ”ngx_evenht_bipe_wtite_to_downstteam 方法 的 流程 图 





8) 取出 in 链表 首部 的 第 一 个 绥 冲 区 准备 发 送 ， 所 有 步骤 与 第 7 步 相同 。 












































9) 将 刚才 调用 ngx_event_pipe_free_shadow_raw_buf 方 法 处 理 过 的 绥 冲 区 再 添加 到 out 链 表 首 部 〈 待 发 送 的 内 容 都 添 力 


























10) 检查 out 链 表 以 及 之 前 各 个 步骤 中 是 否 有 需要 发 送 的 内 容 〈 其 实 是 通过 一 个 局 部 变量 fush 作 为 标志 位 来 表示 是 否 

















11) 调用 output_filter 方 法 向 下 游 故 送 out 绥 冲 


jxl 





12) 调用 ngx chain update_chains 方 法 更 新 free、busy、out 绥 冲 区 。 在 图 12-8 的 第 4 步 中 曾经 介绍 过 该 方法 ， 不 再 袭 述 




















13) 通 历 free 链 表 中 的 缓冲 区 ， 释 放 缓 冲 区 中 的 shadow 域 ， 这 样 ， 这 些 暂 不 使 用 的 缓冲 区 才 可 以 继续 用 来 接收 新 的 3 























至 此 ，buffering 配 置 为 1 时 转发 上 游 啊 应 到 下 游 的 整个 流程 束 全 部 介绍 完了 ， 它 的 流程 复杂 ， 但 效率 很 高 ， 作 为 反问 
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12.9 ”结束 upstream 请 求 


当 Nginx 与 上 游 服务 器 的 交互 出 错 ， 或 者 正常 处 理 完 来 自 上 游 的 啊 应 时 ， 束 需要 结束 请 
求 了 。 这 时 当然 不 能 调用 第 11 章 中 介绍 的 ngx_http finalize request 方 法 来 结束 请 求 ， 这 样 
upstream 中 使 用 到 的 资源 (如 与 上 游 间 建立 的 TCP 连 接 ) 将 无 法 释放 ， 事 实 上 ，upstream 机 . 制 | 
提供 了 一 个 类 似 的 方法 ngx http_upstream finalize request 用 于 结束 upstreami 请 求 ， 在 12.9.1 节 
中 将 会 详细 介绍 这 个 方法 。 除 了 直接 调用 ngx http upstream finalize request 方法 结束 请 求 以 
外 ， 还 有 两 种 独特 的 结束 请 求 方法 ， 分 别 是 ngx_http_upstream cleanup 方 法 和 
ngx http_upstream next 方 法 。 


在 启动 upstream 机 市 时 ，ngx http upstream cleanup 方 法 会 挂 载 到 请 求 的 cleanup 链 表 中 
(参见 图 12-2 的 第 3 步 ) ， 这 样 ，HTTP 框 架 在 请 求 结束 时 就 会 调用 ngx_ http_upstream cleanup 
方法 (参见 11.10.2 广 ngx_http_free_request 方 法 的 流程 》， 这 保证 了 ngx_http_upstream cleanup 
一 定 会 被 调用 。 而 ngx_http upstream cleanup 方 法 实际 上 还 是 通过 调用 
ngx http upstream finalize request 来 结束 请 求 的 ， 如 下 所 示 。 





static void ngx http upstream cleanup (void *data) { 
ngx http request t *r = data; 


ngx http upstream t *u = r->upstream; … 


/* 最 终 还 是 调用 


ngx_ http upstream finalize request 方 法 来 结束 请 求 ， 注 意 传递 的 是 
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NGX_DONE 参数 


人 





ngx http upstream finalize request(r, u, NGX DONE); } 





当 处 理 请 求 的 流程 中 出 现 错误 时 ， 往 往 会 调用 ngx http upstream next 方 法 。 例 如 ， 在 图 
12-5$ 中 ， 如 果 在 接收 上 游 服 务 器 的 包头 时 出 现 错误 ， 接 下 来 就 会 调用 该 方法 ， 这 是 因为 
upstream 机 制 还 提供 了 一 个 较为 灵活 的 功能 : 当 与 上 游 的 交互 出 现 错误 时 ，Nginx 并 不 想 立 刻 
认为 这 个 请 求 处 理 失败 ， 而 是 试图 多 给 上 游 服务 器 一 些 机 会 ， 可 以 重新 问 这 人 台 或 者 另 一 台 上 
游 服务 器 发 起 连接 、 发 送 请 求 、 接 收 啊 应 ， 以 避免 网 络 故障 。 这 个 功能 可 以 帮助 HITP 模 块 
实现 简单 的 负载 均衡 机 制 〈 如 最 常见 的 HTTP 反 向 代理 模块 ) 。 而 该 功能 正 是 通过 
ngx_http_upstream next 方 法 实现 的 ， 因 为 该 方法 在 结束 请 求 之 前 ， 会 检查 
ngx_peer_connection t 结 构 体 的 tries 成 员 〔 参 见 9.3.2 节 ) 。tries 成 员 会 初始 化 为 每 个 连接 的 最 
大 重 试 次 数 ， 每 当 这 个 连接 与 上 游 服务 占 出 现 错误 时 就 会 把 tries 减 1。 在 出 错时 
ngx_http_upstream next 方 法 首先 会 检查 tries， 如 果 它 减 到 0， 才 会 真正 地 调用 
ngx_http_upstream finalize_request 方 法 结束 请 求 ， 奋 则 不 会 结束 请 求 ， 而 是 调用 
ngx_http_upstream connect 方 法 重新 问 上 游 发 起 请 求 ， 如 下 所 示 。 








static void ngx http upstream next (ngx http request t *r, ngx http upstream t *u, ngx uint t ft type) { 


/* 只 有 向 这 人 台 上 游 服务 器 的 重 试 次 数 


tries 减 为 
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0 时 ， 才 会 真正 地 调用 


ngx_httpP_upstream finalize request 方法 结束 请 求 ， 否 则 会 再 次 试图 重新 与 上 游 服务 器 交互 ， 这 个 功能 将 帮助 感 兴趣 的 





HTTP 模 块 实现 简单 的 负载 均衡 机 制 。 


u->conf->next_upstream 表 示 的 含义 在 


32 位 的 错误 码 组 合 ， 表 示 当 出 现 这 些 错误 码 时 不 能 直接 结束 请 求 ， 需 要 向 下 一 台 上 游 服务 器 再 次 重 发 
4 
if (u->peer.tries == 0 || !(u->conf->next upstream & ft type)) ({ 


ngx http upstream finalize request(r, u, status); return; 


// 如 果 与 上 游 间 的 


TCP 连 接 还 存在 ， 那 么 需要 关闭 
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ngx close connection(u->peer.connection); u->peer.connection = NULL; 





// 重新 发 起 连接 ， 参 见 


12.3 节 


ngx http upstream connect(r, u); 





下 面 来 看 一 下 ngx_http upstream finalize request 到 底 做 了 些 什 么 工作 。 


ngx http_ upstream finalize request 方 法 还 是 会 通过 调用 HTTP 框 架 提 供 的 
ngx_http_finalize request 方法 释放 请 求 ， 但 在 这 之 前 需要 释放 与 上 游 交 互 时 分 配 的 资源 ， 如 文 
件 句 柄 、TCP 连 接 等 。 它 的 源 代 码 很 简单 ， 下 面 直 接 列 举 其 源 代 码 说 明 它 所 做 的 工作 。 








static void ngx http upstream finalize request (ngx httpP request t *r, ngx http upstream t *u, ngx int t rc) { 
ngx time t *tp; 


// 将 


cleanup 指 向 的 清理 资源 回调 方法 置 为 


NULL 空 指针 
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if (u->cleanup) { 


*u->cleanup = NULL; 


u->cleanup = NULL; 


// 释放 解析 主机 域名 时 分 配 的 资源 


if (u->resolved && u->resolved->ctx) { 





ngx resolve name done(u->resolved->ctx); u->resolved->ctx = NULL; 


if (u->state && u->state->response sec) { 





// 设置 当前 时 间 为 


HTTP 响 应 结束 时 间 


tp = ngx timeofday(); 











U=>state=>response See = tp=>8eCc = UU=>8tate=>response Sec; UU->state=>response msec =: tp=>msec: = U=>Statt 


u->state->response length = u->pipe->read length; } 





/和 
[ 


用 
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HTTP 模 块 负责 实现 的 


finalize request 方 法 。 


HTTP 模 块 可 能 会 在 


upstream 请 求 结 束 时 执行 一 些 操 作 


4 


u->finalize request(r, rc); 


/* 如 果 使 用 了 


TCP 连 接 池 实 现 了 


free 方 法 ， 那 么 调用 


free 方 法 (如 


ngx_http_upstream free round robin peer) 释放 连接 资源 





Sy 


站 “PEPET NNN http://ww linuxorobe. con 





uU->peer .free(&u->peer，u->peer.dqata 0); } 


// 如 果 与 上 游 间 的 


TCP 连 接 还 存在 ， 则 关闭 这 个 


TCP 连 接 


if (u->peer.connection) { 


ngx close connection(u->peer.connection); } 





u->peer.connection = NULL; 





if (u->store && u->pipe && u->pipe->temp file && u->pipe->temp file->file.fd != NGX INVALID FILE 


一 





/* 如 果 使 用 了 磁盘 文件 作为 缓存 来 向 下 游 转发 响应 ， 则 需要 删除 用 于 缓存 响应 的 临时 文件 


4 








if (ngx delete file(u->pipe->temp file->file.name.data) == NGX FILE ERROR) 











ngx log error (NGX LOG CRIT, r->connection->log, ngx errno, ngx delete file n " \"%s\" failed", u->p: 


/x 如 果 已 经 向 下 游客 户 端 发 送 了 


HTTP 响 应 头 部 ， 却 出 现 了 错误 ， 那 么 将 会 通过 下 
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ngx http send special(r，NGX HTTP LAST) 将 头 部 全 部 发 送 完 毕 


















































4 
if (u->header Sent && rc != NGX HTTP REQUEST TIME OUT 
&& (rc == NGX ERROR || rc >= NGX HTTP SPECIAL RESPONSE)) { 
re = 0; 
} 
if (rc == NGX DECLINED) { 
return; 
} 
r->connection->log->action = "sending to client"; if (rc == 0) 
{ 
rc = ngx http send speciall(r, NGX HTTP LAST); } 
/* 最 后 还 是 通过 调用 
HTTP 框 架 提供 的 
ngx http finalize request 方 法 来 结束 请 求 
4 


ngx http finalize request(r, rc); 
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12.10， 小结 





本 章 介 绍 的 upstream 机 制 也 属于 HTTP 框架 的 一 部 分 ， 它 同样 是 基于 事件 框架 实现 了 异步 
访问 上 游 服务 器 的 功能 ， 同 时 ， 它 并 不 满足 于 仅仅 帮助 应 用 级 别 的 HTTP 模块 基于 TCP 访 问 
上 游 ， 而 是 提供 了 非常 强大 的 转发 上 游 响应 功能 ， 而 且 在 转发 方式 上 更 加 灵活 、 高 效 ， 并 且 
对 于 内 存 的 使 用 相当 节省 ， 这 些 功 能 帮助 Nginx 的 ngx_http_proxy module 模 块 实现 了 强大 的 反 
向 代理 功能 。 同 时 ， 配 合 着 ngx http upstream ip hash module 或 者 Round Robin 相 关 的 代码 
(它们 负责 管理 ngx_ peer_connection t 上 游 连接 ) ，ngx_http_upstream next 方法 还 可 以 帮助 
HTTP 模 块 实现 简单 的 负载 均衡 功能 。 











由 于 upstream 机 制 属于 HTTP 框 名 ， 所 以 它 仪 抽象 出 了 通用 代码 ， 而 尽量 地 把 组 装 发 往 上 
游 请 求 、 解 析 上 游 啊 应 的 部 分 都 交 给 使 用 它 的 HITP 模 块 实现 ， 这 使 得 使 用 upstream 的 HITP 
模块 不 会 太 复杂 ， 而 性 能 却 非常 高 效 ， 算 是 在 灵活 性 和 简单 性 之 间 找 到 了 一 个 平衡 点 。 在 阅 
读 完 本 章 后 ， 我 们 就 有 可 能 写 出 非常 强大 的 访问 第 三 方 服务 器 的 代码 了 ， 在 这 个 过 程 中 ， 尽 
量 使 用 upstream 已 经 提供 的 各 种 功能 ， 将 会 简化 HTTP 模 块 的 开发 过 程 。 
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第 13 章 ”邮件 代理 模块 


本 章 将 说 明 Nginx 官 方 提 供 的 一 系列 邮件 模块 ， 这 些 邮 件 模块 配合 Nginx 事 件 框架 共同 构 
建 了 文 持 POP3、SMIP、IMAP 这 3 种 协议 的 邮件 代理 服务 器 ， 它 们 把 邮件 代理 服务 局 的 主要 
功能 抽象 成 一 个 类 似 于 HTTP 框 架 的 邮件 框架 ， 以 灵活 地 支持 Nginx 扩 展 更 多 的 邮件 协议 ， 而 
POP3、SMTP、IMAP 模 块 将 作为 普通 的 邮件 模块 使 用 这 套 框架 。 作 为 邮件 代理 服务 器 的 
Nginx 昌 然 也 访问 上 游 服务 器 ， 但 由 于 它 不 使 用 HTTP 框 架 ， 所 以 无 法 使 用 第 12 章 介绍 的 
upstream 机 制 ， 然 而 “邮件 代理 ?其实 同 样 具 有 部 分 的 反 向 代理 功能 ， 本 章 13.7 节 介绍 的 透 伟 
TCP 部 分 其 实 也 有 点 像 一 个 简化 版 的 upstream 机 制 。 





本 章 首 先 介绍 邮件 代理 功能 到 后 做 了 哪些 事情 ， 接 下 来 会 分 析 Nginx 如 何 实现 邮件 代理 
功能 。 实 际 上 ， 本 章 更 像 是 第 10 半 ~ 第 12 半 的 简化 版 本 ， 所 以 在 本 章 中 将 不 会 再 次 描述 曾经 
介绍 过 的 如 何 异 步 地 、 无 阻 暑 地 提供 服务 ， 以 及 如 何 使 用 epoll、 定 时 右 等 事件 框架 。 读 者 也 
应 当 熟 悉 Nginx 的 这 套 设计 方法 了 ， 因 此 本 革 仅 会 描述 邮件 模块 的 主要 阶段 ， 不 会 深入 细 
节 。 另 外 ， 本 章 也 不 会 详细 说 明 POP3、SMTP、IMAP， 因 为 Nginx 并 非 真 正 的 邮件 服务 器 。 
本 章 的 重点 在 于 了 解 邮件 代理 服务 器 的 使 用 方法 ， 以 及 应 该 如 何 扩展 邮件 代理 模块 的 功能 ， 
同时 了 解 通 过 邮件 模块 继续 熟悉 Nginx 事 件 框架 的 用 法 ， 继 而 熟悉 如 何 利用 它 开 发 高 性 能 服 
务 器 。 
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13.1 ”邮件 代理 服务 器 的 功能 


在 第 8 半 中 介绍 过 邮件 模块 ， 它 提供 了 邮件 代理 服务 器 的 功能 。 什 么 是 邮件 代理 服务 
器 ? 顾名思义 ， 它 不 会 提供 实际 的 邮件 服务 器 功能 ， 而 是 把 客户 问 的 请 求 代 理 到 上 游 的 邮件 
服务 嚣 中。 那么， 客户 端 为 何不 直接 访问 真正 的 邮件 服务 器 ， 反 而 多 此 一 举 地 访问 邮件 代理 
服务 器 呢 ? 原因 可 以 在 后 续 章 节 描 述 的 Nginx 实 现 中 找到 ， 其 中 最 重要 的 是 Nginx 并 不 是 简单 
地 透 传 邮件 协议 到 上 游 ， 它 还 有 一 个 认证 的 过 程 ， 如 图 13-1 所 示 。 








从 图 13-1 中 可 以 看 出 ，Nginx 在 与 下 游客 户 端 交互 过 程 中 ， 还 会 访问 认证 服务 大 ， 只 有 
认证 服务 器 通过 了 并 且 被 告知 Nginx 上 游 的 邮件 服务 名 地 址 后 ，Nginx 才 会 同上 游 的 邮件 服务 
需 发 起 通信 请 求 。 同 时 ，Nsginx 可 以 解析 客户 问 的 协议 获得 必要 的 信息 ， 接 下 来 它 还 可 以 根 
据 客 户 端 发 来 的 信息 快速 、 独 立地 与 邮件 服务 器 做 简单 的 认证 交互 ， 之 后 才 会 开始 在 上 、 下 
游 之 间 透 传 TCP 流 。 这 些 行为 都 意味 着 Nginx 的 高 并 发 特性 将 会 降低 上 游 邮 件 服务 器 的 并 发 压 
力 。 
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POP3 邮 件 服 务 需 了 2 务 嚣 SMTP 邮 件 服务 器 


wa o1HX HTTP 认 证 服务 病 


邮件 客户 靖 


图 13-1 Nginx 在 邮件 代理 场景 中 的 位 置 





Nginx 与 下 游客 户 端 、 上 游 邮件 服务 器 间 都 是 使 用 邮件 协议 ， 而 与 认证 服务 器 之 间 却 是 
通过 类 似 HTTP 的 形式 进行 通信 的 。 例 如 ， 发 往 认 证 服务 器 的 请 求 如 下 所 示 : 





GET auth HTTP1.0 
Host: auth.server.hostname 





Auth-Method: plain 
Auth-User: user 
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Auth-Protocol: imap 
Auth-Login-Attempt: 1 
Client-IP: 192.168.1.1 





而 认证 服务 器 会 返回 最 常见 的 成 功 啊 应 ， 即 类 似 下 面 的 字符 流 : 





HTTP/1.0 200 OK 
Auth-Status: OK 
Auth-Server: 192.168.1.10 
Auth-Port: 110 

Auth-User: newname 





当然 ， 认 证 服务 器 的 返回 要 复杂 得 多 。 由 于 本 章 既 不 会 介绍 认证 服务 器 如 何 实现 ， 也 不 
会 介绍 上 游 的 邮件 服务 器 如 何 实现 ， 所 以 对 协议 部 分 不 会 继续 深入 介绍 。 


一 般 情况 下 ， 客 户 端 发 起 的 邮件 请 求 在 经 过 Nginx 这 个 邮件 代理 服务 器 后 ， 网 络 通信 过 
程 如 图 13-2 所 示 。 


从 网 络 通信 的 角度 来 看 ，Nginx 实 现 邮件 代理 功能 时 会 把 一 个 请 求 分 为 以 下 4 个 阶段 。 
` 接收 并 解析 客户 端 初始 请 求 的 阶段 。 

. 向 认证 服务 器 验证 请 求 合法 性 ， 并 获取 上 游 邮件 服务 器 地 址 的 阶段 。 

* Nginx 根 据 用 户 信息 多 次 与 上 游 邮件 服务 器 交互 验证 合法 性 的 阶段 。 

- Nginx 在 客户 端 与 上 游 邮 件 服务 器 间 纯 粹 透 传 TCP 流 的 阶段 。 


由 此 可 以 了 解 到 ， 这 些 Nginx 邮 件 模块 的 目的 非常 明确 ， 就 是 使 用 事件 框架 在 大 量 并 发 
连接 下 高 效 地 处 理 这 4 个 阶段 的 请 求 。 
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好 件 服务 多 
| | 


i ”用 户 铺 求 | 





| 
| 
| 
类 HTTP 认 证 请 求 ， 






认证 啊 应 


| 
发 起 TCP 连 接 


欢迎 消息 


验证 用 户 名 、 密 码 等 
















P'OQiP 3 、 
SMTP、IMAP 
等 协议 需要 响应 
2 
都 不 相同 






转发 上 游 的 啊 应 


转发 上 游 的 请 求 


Nginx 将 开始 在 
客户 端 与 邮件 服 
务 絮 之 间 双 向 透 
传 TCP 流 








啊 应 


图 13-2 ”邮件 代理 功能 的 示意 序列 图 


为 了 让 读者 对 邮件 代理 服务 器 有 直观 的 认识 ， 下 面 再 来 看 看 nginx.conf 配 置 文件 。 邮 件 模 
块 定义 的 nginx.conf 配 置 文件 与 HTTP 模 块 非常 相似 。 例 如 ， 和 常见 的 配置 可 能 束 像 下 面 的 这 上段 
配置 一 样 。 
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// 邮件 认证 服务 器 的 访问 


URL 
auth http IP:PORT/authn.php; 
// 当 透 传 上 、 下 游 间 的 


TCP 流 时 ， 每 个 请 求 所 使 用 的 内 存 缓冲 区 大 小 


proxy buffer 4k; 
server { 


/* 对 于 


POP3 协 议 ， 通 常 都 是 监听 


110 端 口 。 


POP3 协 议 接 收 初 始 客户 端 请 求 的 缓冲 区 固定 为 


128 字 节 ， 配 置 文件 中 无 法 设置 


*y 
listen 110; 
protocol pop3; 
proxy on; 


listen 143; 
protocol imap; 
// 设置 接收 初始 客户 端 请 求 的 缓冲 区 大 小 


imap client buffer 4k; 
proxy on; 
} 


server { 


// 对 于 


listen 25; 
protocol smtp; 
proxy on; 


// 设置 接收 初始 客户 端 请 求 的 缓冲 区 大 小 


smtp client buffer 4k; 
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mail 人 } 块 下 的 配置 项 将 会 被 本 章 介 绍 的 邮件 模块 所 使 用 。 束 和 像 HTTP 模 块 中 的 配置 一 
样 ， 直 属于 mail 介 块 下 的 配置 称 为 main 级 别 的 配置 ， 而 在 server{} 块 下 的 配置 则 称 为 svr 配 置 
(不 使 用 HTTP， 故 没有 loc 级 别 的 配置 )。 
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13.2 ”邮件 模块 的 处 理 框 架 


本 节 首 先 会 从 总 体 上 说 明 邮 件 框架 是 如 何 处 理 请 求 的 ， 接 着 会 介绍 这 一 新 的 模块 类 型 有 
什么 样 的 接口 ， 以 及 应 当 如 何 定义 ， 最 后 将 会 简单 地 说 明 邮 件 框架 的 初始 化 过 程 。 


13.2.1 一 个 请 求 的 8 个 独立 处 理 阶 段 


图 13-2 大 致 介绍 了 请 求 的 处 理 过 程 ， 而 对 于 邮件 框架 而 言 ， 通 常 可 以 把 请 求 的 处 理 过 程 
分 为 8 个 阶段 。 这 里 “阶段 ”的 划分 依据 是 什么 呢 ? 由 于 Nginx 是 异步 的 、 非 阻塞 的 处 理 方式 ， 
所 有 负责 独立 功能 的 一 个 《或 者 几 个 ) 方法 可 能 被 epoll 或 者 定时 器 无 数 次 地 驱动 、 调 度 ， 故 
而 可 以 把 相同 代码 可 能 被 反复 多 次 调用 的 过 程 称 为 一 个 阶段 。 下 面 按 照 这 种 划分 方式 ， 把 请 
求 分 为 8 个 阶段 ， 如 图 13-3 所 示 。 
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1) 初 始 化 邮件 


请 求 


2 ) 接 收 并 解析 客户 


端 请 求 阶段 


3) 回 认证 服务 天 发 起 
TCP 连接 阶段 


4) 回 认证 服务 硕 发 送 


请 求 阶段 





5 ) 接 收 并 解析 认证 服务 天 
的 啊 应 阶段 





6) 回 上 游 邮 件 服 务 硕 
发 起 连接 阶段 








7) 与 邮件 服务 需 交 互 
已 知 信息 阶段 


8) 双 回 透 传 下 游客 户 端 与 上 游 
邮件 服务 侣 的 内 容 
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图 13-3 ”邮件 框架 中 处 理 一 个 请 求 的 主要 阶段 


这 8 个 阶段 必须 依次 同 下 进行 ， 它 们 的 意义 如 下 。 





1) 当 客 户 端 发 起 的 TCP 连 接 建立 成 功 时 ， 就 会 回调 邮件 框架 初始 化 时 设 定 的 
ngx_mail_ init_ connection 方 法 ， 在 这 个 方法 中 会 初始 化 将 要 用 到 的 数据 结构 ， 并 设置 下 一 个 阶 
段 的 处 理 方 法 。 











2) 接收 、 解 析 客 户 端的 请 求 。 这 个 阶段 会 读 取 客 户 问 及 来 的 TCP 流 ， 并 使 用 状态 机 解 
析 它 ， 如 末 解 析 后 发 现 已 接收 到 完整 的 请 求 ， 则 进入 下 一 阶段 ;人 否则， 将 会 继续 把 连接 上 的 
读 事 件 添加 a 到 epoll 中 ， 并 等 等 epoll 的 下 一 次 调度 ， 以 便 继续 读 取 客户 端 请 求 。 


3) 解析 到 完整 的 请 求 后 ， 就 需要 问 认 证 服务 器 发 起 类 似 HITP 的 请 求 来 验证 请 求 是 否 合 
法 。Nginx 与 认证 服务 器 间 仍 然 是 通过 TCP 通 信 的 ， 发 起 三 次 握手 自然 算是 一 个 独立 的 阶段 。 


4) 当 Nginx 与 认证 服务 器 成 功 建立 TCP 连 接 时 ，ngx_mail auth_http_ module 模块 将 会 构 
造 、 发 送 请 求 到 认证 服务 器 。 在 13.4.3 节 中 将 要 介绍 的 ngx_mail auth_ http_ write_ handler 方 法 
会 确保 全 部 的 请 求 都 发 送 到 认证 服务 器 中 。 


5) Nginx 接 收 认 证 服务 器 的 响应 是 通过 ngx mail auth http read handler 完 成 的 ， 在 该 方 
法 中 ， 每 接收 一 部 分 啊 应 都 要 使 用 状态 机 来 解析 ， 在 接收 完整 的 响应 〈 包 括 响应 行 和 HTTP 
头 部 ) 后 ， 还 会 分 析 啊 应 结果 以 确定 请 求 是 否 合法 ， 如 有 果 合 法 ， 将 继续 执行 下 一 阶段 。 





6) 这 一 阶段 将 从 认证 服务 器 返回 的 响应 中 获得 上 游 邮 件 服务 器 的 地 址 ， 接 着 同上 游 邮 
件 服 务 器 发 起 TCP 连 接 。 


7) 在 TCP 连 接 建 立成 功 后 ， 接 下 来 是 Nginx 与 邮件 服务 器 使 用 POP3、SMTP 或 者 IMAP 交 


互 的 阶段 。 这 一 过 程 主 要 是 Nginx 将 请 求 中 的 用 户 、 密 码 、 发 件 人 、 收 件 人 等 信息 传递 给 邮 
件 服务 器 ， 这 个 过 程 是 双 同 的 ， 直 到 Nginx 认 为 邮件 服务 器 同意 继续 癌 下 进行 时 ， 才 会 继续 
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一 阶段 是 最 主要 的 透 传 邮件 协议 阶段 。 只 要 Nginx 收 到 下 游客 户 并 的 TCP 流 无论 
征 哪 一 种 邮件 协议 ) ， 会 原封 不 动 地 转 及 给 上 游 的 邮件 服务 龙 ， 同 样 ， 如 果 收 到 上 游 的 TCP 
流 ， 也 会 原样 转发 给 下 洲 。 


邮件 框架 的 目标 就 是 健壮 、 高 效 地 处 理 这 8 个 阶段 。 


13.2.2 ”邮件 类 模块 的 定义 








在 第 8 章 说 过 ， 每 一 个 Nginx 模 块 都 会 使 用 ngx module t 结 构 体 来 表示 ， 而 ngx_module t 中 
的 ctx 成 员 将 指 癌 各 种 模块 的 特有 接口 。 


首先 介绍 的 邮件 模块 是 NGX CORE MODULE 类 型 的 nex mail module 模 块 ， 它 定义 了 一 
种 新 的 模块 类 型 ， 叫 做 NGX MAIL MODULE。 同 时 ， 它 会 管理 所 有 NGX MAIL MODULE 类 
型 的 邮件 模块 。 这 些 邮件 模块 的 ctx 成 员 指 向 的 抽象 接口 叫做 ngx mail module t， 如 下 所 示 。 





typedef struct { 
// PoP3、 


SMTP、 


IMAP 邮 件 模块 提取 出 的 通用 接口 


ngx mail protocol t protocol; 


/创建 用 于 存储 
main 级 别 配置 项 的 结构 体 ， 该 结构 体 中 的 成 员 将 保存 直属 于 
mail{} 块 的 配置 项 参数 


/ 
void (*create main conf) (ngx conf t cf); 


/解析 完 


main 级 别 配置 项 后 被 回调 
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/* 创 建 用 于 存储 


srv 级 别 配 置 项 的 结构 体 ， 该 结构 体 中 的 成 员 将 保存 直属 于 


server{} 块 的 配置 项 参数 


六 
void (*create srv conf) (ngx conf t cf); 


/svr 级 别 可 能 存在 与 


main 级 别 同名 的 配置 项 ， 该 回调 方法 会 给 具体 的 邮件 模块 提供 一 个 手段 ， 以 便 从 


prev 和 


conf 参 数 中 获取 到 已 经 解析 完毕 的 


main 和 


srv 配 置 项 结构 体 ， 自 由 地 重新 修改 它们 的 值 


/ 
char (*merge srv conf) (ngx conf 七 cf, void prev, void *conf); 
} ngx mail module t; 





每 一 个 邮件 模块 都 会 实现 ngx mail module t 接 口 。 除 了 最 上 面 的 protocol 成 员 以 外 ， 其 实 
ngx_mail module t 与 ngx_http_module t 非 党 相似， 当然 ， 那 些 同名 成 员 的 功能 也 是 相似 的 。 
下 面 看 一 下 这 个 protocol 接 口 定义 了 哪些 内 容 。 





typedef struct ngx mail protocol s ngx mail protocol t; 
// 4 个 


ROP3% 


SMTP、 


IMAP 等 应 用 级 别 的 邮件 模块 所 要 实现 的 接口 方法 


typedef void (*ngx mail init session pt) (ngx mail session 七 Sv 
ngx connection t c); 
typedef void (*ngx mail init Protocol pt) (ngx event t rev); 
typedef void (ngx mail auth state pt) (ngx event t rev); 
typedef ngx int t (ngx mail parse command pt) (ngx mail session t *s); 
struct ngx mail Protocol s { 


// 邮件 模块 名 称 








ngx_ str t name; 


// 当前 邮件 模块 中 所 要 监听 的 最 常用 的 
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4 个 端口 


in port t port[4]; 
/* 邮 件 模块 类 型 。 目 前 


type 仅 可 以 取 值 为 : 


NGX MAIL POP3 PROTOCOL., 


NGX MAIL IMAP PROTOCOL., 














NGX MAIL SMTP PROTOCOL*/ 
ngx uint t type; 
// 与 客户 端 建立 起 


TCP 连 接 后 的 初始 化 方法 


ngx mail init session pt init session; 


// 接收 、 解 析 客户 端 请 求 的 方法 


ngx mail init protocol pt init protocol; 


// 解析 客户 端 邮件 协议 的 接口 方法 ， 由 


POP3、 


SMTP、 


IMAP 等 邮件 模块 实现 


ngx mail parse command pt parse command; 
// 认证 客户 端 请 求 的 方法 


ngx mail auth state pt auth state; 
/* 当 处 理 过 程 中 出 现 没有 预见 到 的 错误 时 ， 将 会 返回 








internal server error 指 定 的 响应 到 客户 端 


ngx str 七 int rnal s rver error; 








可 以 看 到 ，ngx mail protocol t 接 口 定 义 了 POP3、SMTP、IMAP 等 应 用 级 别 的 邮件 模块 
加 入 到 邮件 框架 时 所 要 实现 的 接口 以 及 需要 遵循 的 规则 。 





关于 POP3、SMTP、IMAP 模 块 的 定义 ， 这 里 不 再 介绍 ， 读 者 可 以 自行 查看 Nginx 源 代 
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码 。 在 下 面 的 章节 中 ， 读 者 将 看 到 它们 如 何 结合 邮件 框架 来 实现 邮件 代理 功能 。 
13.2.3 ”邮件 框架 的 初始 化 
当 nginx.conf 文 件 中 出 现 mail{} 或 者 imap 人 {配置 项 时 ，ngx_mail module 模 块 就 从 


ngx_mail_block 方 法 开始 它 的 初始 化 过 程 ( 与 第 10 章 中 的 HTTP 框 架 非常 相似 ) ， 如 网 13-4 所 


人 。 


NNNn httpo://ww linuxorobe. con 





初始 化 每 一 个 邮件 模块 的 


ctx_index 夺 号 


分 配 存放 main 级 别 配 置 项 、svr 
级 别 配 置 项 指针 的 两 个 指针 数组 


调用 所 有 邮件 模块 的 create_main_conf 
方法 创建 存放 main 配 置 项 的 结构 体 


调用 所 wi i- Teate _Ccrv_cont 
他 i 时 项 的 结 校 


调用 有 所 有 邮件 模块 的 
init_main_conf 方 法 


人 有 wal 的 ee SrV or 





构造 监听 端口 与 server 配 置 块 间 的 关联 关系 ， 
设置 新 连接 事件 的 回调 方 ; 
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图 13-4 ”邮件 框架 初始 化 的 流程 图 





上 述 过 程 实际 上 就 是 图 10-9 的 简化 版 ， 这 里 不 再 细 说 。 其 中 最 后 一 步 中 设置 的 TCP 连 接 
建立 成 功 后 的 回调 方法 为 ngx mail init connection， 在 13.3 节 中 会 说 明 此 方法 。 
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13.3 ”初始 化 请 来 


Nginx 与 客户 端 建立 TCP 连 接 后 ， 将 会 回调 ngx mail init connection 方 法 开始 初始 化 邮件 
协议 ， 这 是 在 处 理 每 个 邮件 请 求 前 必须 要 做 的 工作 。 其 中 ， 初 始 化 请 求 时 将 会 创建 类 似 于 
HTTP 请 求 中 的 ngx http_ request t 这 样 的 核心 结构 体 ; ngx _ mail session t， 在 13.3.1 节 中 将 会 对 
它 进行 介绍 。 另 外 ， 在 13.3.2 节 中 会 说 明 TCP 连 接 建立 成 功 时 ngx _ mail init connection 方 法 到 
底 做 了 哪些 工作 。 





13.3.1 ” 摘 述 邮件 请 求 的 ngx mail session t 结 构 体 


ngx_mail_session t 结 构 体 保存 了 一 个 邮件 请 求 的 生命 周期 里 所 有 可 能 用 到 的 元 素 ， 如 下 
所 示 。 





typedef struct { 


// 目前 未 使 用 


uint32 t signature; 
// 下 游客 户 端 与 


Nginx 之 间 的 连接 


ngx connection t *connection; 


// out 中 可 以 存放 需要 向 下 游客 户 端 发 送 的 内 容 
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ngx_ str t out; 


/* 这 个 缓冲 区 用 于 接收 来 自 客户 端的 请 求 。 这 个 缓冲 区 中 所 使 用 的 内 存 大 小 与 请 求 是 有 关系 的 ， 对 于 


POP3 请 求 固定 为 


128 字 节 ， 对 于 


SMTP 请 求 ， 由 


nginx.conf 配 置 文件 中 的 


smtp_client buffer 配 置 项 决定 ， 对 于 


IMAP 请 求 ， 则 由 


imap_client buffer 配 置 项 决定 


*/ 
ngx buf t *pbuffer; 
/*ctx 将 指向 一 个 指针 数组 ， 它 的 含义 与 
HTTP 请 求 的 
ngx http request t 结 构 体 中 的 
Ctx 一 致 ， 保 存 着 这 个 请 求 中 各 个 邮件 模块 的 上 下 文 结构 体 指 针 
#y 


void **ctx; 


// main 级 别 配置 结构 体 组 成 的 指针 数组 


void **main conf; 
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/*srv 级 别 配 置 结构 体 组 成 的 指针 数组 ， 这 两 个 指针 数组 的 意义 与 第 


10 章 介绍 过 的 


HTTP 框 架 中 的 同名 数组 基本 一 致 ， 只 是 它们 是 用 于 


main{} 配 置 块 下 的 配置 结构 体 


*/ 
VOLd. **srv GE 
// 解析 主机 域名 
ngx resolver ctx 七 *resolver ctx; /x* 请 求 经 过 认证 后 ， 
Nginx 就 开始 代理 客户 端 与 邮件 服务 器 间 的 通信 了 ， 这 时 会 生成 
proxy 上 下 文 用 于 此 目的 ， 详 见 
13:55 节 
*y 


ngx mail proxy ctx 七 *proxy; 





/* 表 示 与 邮件 服务 器 交互 时 ， 当 前 处 理 哪 种 状态 。 对 于 
POP3 请 求 来 说 ， 会 隶属 于 
ngx pop3 _ state e 定 义 的 
7 种 状态 ; 对 于 
IMRAP 请 求 来 说 ， 会 隶属 于 


ngx imap state e 定 义 的 


TNTNNNinNnnn http://wWwWw linuxorobe.con 





8 种 状态 ; 对 于 


SMTP 请 求 来 说 ， 会 来 属于 


ngx _ smtp state e 定 义 的 


13 种 状态 


*/ 


ngx uint t mail state; 


// 邮件 协议 类 型 目前 仅 有 以 下 





3 外 
// #define NGX MAIL POP3 PROTOCOL 0 
// #define NGX MAIL IMAP PROTOCOL 1 
// #define NGX MAIL SMTP PROTOCOL 2 
unsigned protocol:3; 
// 标志 位 。 

blocked 为 


1 时 表示 当前 的 读 或 写 操 作 需 要 被 阻塞 


unsigned blocked:1; 
// 标志 位 。 


quit 为 
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unsigned quit:1; 


// 以 下 


3 个 标志 位 仅 在 解析 具体 的 邮件 协议 时 由 邮件 框架 使 用 


unsigned quoted:1; 


unsigned backslash:1; 


unsigned no sync literal:1; 


/* 当 使 用 


SSL 协 议 时 ， 该 标志 位 为 


1 说 明 使 用 


TLS 传 输 层 安全 协议 。 由 于 本 书 不 涉及 


SSL， 故 略 过 


*/ 


unsigned starttls:1; 


/* 表 示 与 认证 服务 器 交互 时 的 记录 认证 方式 。 目 前 有 


6 个 预 设 值 ， 分 别 是 : 


#define NGX MAIL AUTH PLAIN 0 








#define NGX MAIL AUTH LOGIN 
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define NGX MAIL AUTH LOGIN USERNAME 2 
define NGX MAIL AUTH APOP 3 
define NGX MAIL AUTH CRAM MD5 4 
define NGX MAIL AUTH NONE 5 7 





unsigned auth method:3; 
/* 用 于 认证 服务 器 的 标志 位 ， 为 
1 时 表示 得 知 认证 服务 器 要 求 暂缓 接收 响应 ， 这 时 
Nginx 会 继续 等 待 认证 服务 器 的 后 续 响 应 
Wa 
unsigned auth wait:1; 
/x* 用 于 验证 的 用 户 名 ， 在 与 认证 服务 器 交互 后 会 被 设 为 认证 服务 器 返回 的 响应 中 的 
Auth-User 头 部 
Wh 
ngx str 七 login; 
/* 相 对 于 
login 用 户 名 的 密码 ， 在 与 认证 服务 器 交互 后 会 被 设 为 认证 服务 器 返回 的 响应 中 的 
Auth-Pass 头 部 
Sy 
ngx str t passwd; 


// 作为 
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Auth-Salt 验 证 的 信息 


ngx str t salt; 


人 


3 个 成 员 仅 用 于 


IMAP 通 信 


on 


ngx str t tag; 

ngx str t tagged line; 
ngx str t text; 

// 当前 连接 上 对 应 的 


Nginx 服 务 器 地 址 


ngx_ str 七 *addr text; 


// 主机 地 址 


ngx str t host; 
/到 下 
4 个 成 员 仅 用 于 


SMTP 的 通信 
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unsigned esmtp:1; 

ngx str t smtp helo; 

ngx str t smtp from; 

ngx str 七 smtp to; 

/* 在 与 邮件 服务 器 交互 时 〈 即 与 认证 服务 器 交互 之 后 ， 透 传 上 下 游 
TCP 流 之 前 ) ， 
command 表 示 解 析 自 邮件 服务 器 的 消息 类 型 

*/ 
ngx uint t commang; 


// args 动 态 数 组 中 会 存放 来 自 下 游客 户 端的 邮件 协议 中 的 参数 


ngx array t args; 


// 当前 请 求 尝试 访问 认证 服务 器 验证 的 次 数 


ngx uint t login attempt; 
// 以 下 成 员 用 于 解析 


POP3/IMAP/SMTP 等 协议 的 命令 行 


ngx uint t state; 


uU char *cmd start; 
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u char *arg start; 
u char *arg endgd; 
ngx uint t literal len; 


} ngx mail session t; 


想 要 了 解 邮件 框架 的 处 理 流程 ， 离 不 开 ngx _ mail session t 结 构 体 的 帮助 。 如 果 在 阅读 邮 
件 请 求 的 处 理 过 程 中 过 到 ngx mail session t 结 构 体 的 成 员 ， 那 么 可 以 返回 本 章 查 询 其 意义 。 





13.3.2 ”初始 化 邮件 请 求 的 流程 


初始 化 邮件 请 求 的 流程 非常 简单 ， 如 图 13-5 所 示 。 
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为 请 求 创建 


nex_mail session_t 结构 体 


根据 TCP 连 接 上 | 通 口 找到 对 1 应 的 
SeIVEeT 


we _mail_send 
而 发 送 啊 应 的 方法 


根据 server 配 置 块 里 设置 的 协议 调用 相应 
邮件 模块 的 init_session 方 法 





名 


图 13-5 初始 化 邮件 请 求 的 流程 


实际 上 ， 初 始 化 流程 中 最 关键 的 一 步 就 是 调用 POP3、SMTP、IMAP 等 具体 邮件 模块 实 
现 ngx_mail_protocol t 接 口中 的 init_ session 方法 ， 这 些 邮 件 模 块 会 根据 自己 处 理 的 协议 类 型 初 
始 化 ngx mail_ session tt 结构 体 。 在 POP3、SMTP、IMAP 邮 件 模块 内 实现 的 init_session 方 法 
中 ， 都 会 设置 由 各 自 实现 的 init_protocol 方 法 接收 、 解 析 客 户 端 请 求 ， 这 里 不 再 详细 说 明 每 个 
邮件 模块 是 如 何 实现 init_session 方 法 的 。 
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13.4 接收 并 解析 客户 端 请 求 


无 论 是 POP3、SMTP 还 是 IMAP 邮 件 模块 ， 在 处 理 客 户 问 的 请 求 时 ， 都 是 使 用 
ngx_mail protocol t 接 口中 的 init_ protocol 方 法 完成 的 ， 它 们 的 流程 十 分 相似 : 首先 反复 地 接 
收 客户 端 请 求 ， 并 使 用 状态 机 解析 是 否 收 到 足够 的 信息 ， 直 到 接收 了 完整 的 信息 后 才 会 跳 到 
下 一 个 邮件 认证 阶段 执行 (通过 调用 ngx_mail_ auth 方 法 ) 。 





使 用 状态 机 解析 来 自 客户 端的 TCP 流 的 方法 其 实 就 是 通过 ngx_mail_protocol t 接 口中 的 
parse command 方 法 来 完成 的 ，POP3、SMTP、IMAP 邮 件 模块 实现 的 parse command 方 法 都 在 
ngx_mail parser.c 源 文件 中 。 由 于 本 章 不 涉及 邮件 协议 的 细节 ， 这 里 不 再 一 一 说 明 。 
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13.5 ”邮件 认证 


邮件 认证 工作 由 ngx mail auth 方 法 执行 。 邮 件 认 证 服务 器 的 地 址 在 nginx.conf 文 件 的 
auth _ http 配置 项 中 设置 〈 参 见 13.1 节 ) ， 这 一 认证 流程 相对 独立 ， 其 认证 功能 是 由 
ngx_mail_auth_http_module 邮 件 模块 提供 的 。 在 与 认证 邮件 服务 器 打交道 的 过 程 中 ， 结 构 体 
ngx_mail auth http_ctx tt 会 贯穿 其 始终 ， 它 保存 有 连接 、 请 求 内 容 、 啊 应 内 容 、 解 析 状 态 等 必 
要 的 成 员 ， 在 认证 完 邮件 后 将 会 通过 销毁 内 存 池 来 销毁 这 个 结构 体 。 








13.5.1 ngx mail auth http_ctx t 结 构 体 





ngx_mail auth http_ctx 结构 体 是 在 其 成 员 pool 指 向 的 内 存 池 中 分 配 的 ， 它 的 地 址 实际 上 
保存 在 ngx_mail_ session t 的 ctx 指 针 数 组 中 (实际 上 ， 在 ngx_mail auth http_module 模 块 
ctx_index 成 员 指 出 的 序号 对 应 的 ctx 数 组 元 素 中 ， 相 当 于 该 模块 的 上 下 文 结构 体 ) 。 邮 件 框架 
提供 给 各 个 邮件 模块 的 两 个 方法 用 于 在 ctx 指 针 数 组 中 设置 、 取 出 上 下 文 结构 体 的 地 址 ， 如 下 
所 示 。 





#define ngx mail get module ctx(s, module) (Ss)->ctx[module.ctx index] 





#define ngx mail set ctx(s, c, module) s->ctx[module.ctx index] = Cc; 





其 实际 用 法 跟 HTTP 框 架 中 的 ngx_http_set_ctx 方 法 非常 相似 。 例 如 ， 假 设 指针 ctx 就 是 刚刚 
分 配 的 ngx_mail_ auth_http_ctx_t 结 构 体 地 址 ， 而 s 是 每 个 请 求 的 ngx_mail_session t 结 构 体 指 
针 ， 那 么 可 以 这 样 设置 到 请 求 的 ctx 数 组 中 : 





ngx mail set ctx(s, ctx, ngx mail auth http module); 











下 面 详细 介绍 ngx mail auth http ctx tt 结构 体 中 的 每 个 成 员 。 
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typedef struct ngx mail auth nttp ctx s ngx mail auth http ctx t; // 解析 认证 服务 器 





HTTP 响 应 的 方法 指针 


typedef void (*ngx mail auth http handler pt) (ngx mail _ session t s, ngx mail auth http ctx t ctx); Struct ngx 1 








/* request 缓 冲 区 保存 着 发 往 认 证 服务 器 的 请 求 。 它 是 根据 解析 客户 端 请 求 得 到 的 


ngx mail _ session 七 ， 使 用 


ngx mail auth http _ create redquest 方 法 构造 出 的 内 存 缓 冲 区 。 这 里 的 请 求 是 一 种 类 





HTTP 的 请 求 
*/ 
ngx buf 七 *request; 


// 保存 认证 服务 器 返回 的 类 


HTTP 响 应 的 缓冲 区 。 缓 冲 区 指向 的 内 存 大 小 固定 为 


1KB 
ngx buf 七 *response; 


// Nginx 与 认证 服务 器 间 的 连接 
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ngx Peer connection t peer; 


/* 解 析 来 自 认 证 服务 器 类 


HTTP 的 响应 行 、 头 部 的 方法 (参见 图 


13-6) ， 默 认为 


ngx mail auth http ignore status line 方 法 





4 


ngx mail auth http handler pt handler; /* 在 使 用 状态 机 解析 认证 服务 器 返回 的 类 





HTTP 响 应 时 ， 使 用 


state 表 示 解 析 状 态 


4 


ngx uint t state; 


/* ngx mail auth http parse header line 方 法 负责 解析 认证 服务 器 发 来 的 响应 中 类 





HTTP 的 头 部 ， 以 下 
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4 个 成 员 用 于 解析 响应 头 部 
*/ 
u char *header name start; 
u char *header name end; 
u char *header start; 
u char *header end; 


// 认证 服务 器 返回 的 


Auth-Server 头 部 


ngx str t addr; 


// 认证 服务 器 返回 的 


Auth-Port 头 部 


ngx str t port; 


// 错误 信息 


ngx Str t err 


// Da 
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ngx str 七 errmsg; 


/x* 错 误 码 构成 的 字符 串 。 如 果 认 证 服务 器 返回 的 头 部 里 有 


Auth-Error-Code， 那 么 将 会 设置 到 





errcode 中 。 


errmsg 和 


errcode 在 发 生 错 误 时 会 直接 将 其 作为 响应 发 给 客户 端 
2 
ngx_ str t errcode; 


/* 认 证 服务 器 返回 


Auth-Wait 头 部 时 带 的 时 间 玲 将 会 被 设 到 


sleep 成 员 中 ,而 


Nginx 等 待 的 时 间 也 将 由 
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sleep 维 护 ， 当 


sleep 降 为 


0 时 将 会 设置 


quit 标 志 位 为 


1， 表 示 请 求 非 正常 结束 ， 把 错误 码 返 回 给 用 户 


time t sleep; 


// 用 于 邮件 认证 的 独立 内 存 池 ， 它 的 初始 大 小 为 


ngx Pool 七 *pool; 





13.5.2 与 认证 服务 器 建立 连接 


图 13-6 中 描述 了 ngx_mail_auth 方 法 所 做 的 工作 ， 包 括 初 始 化 与 认证 服务 器 交互 之 前 的 工 


作 、 发 起 TCP 连 接 等 。 
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图 13-6 中 设置 了 Nginx 与 下 游客 户 并 间 TCP 连 接 上 的 读 事件 处 理 方法 为 
ngx_mail_ auth_http_block read， 这 个 方法 所 做 的 唯一 工作 其 实 就 是 再 次 调用 
ngx_ handle read event 方 法 把 读 事 件 又 添加 到 epoll 中 ， 这 意味 着 它 不 会 读 取 任何 客户 端 发 来 
的 请 求 ， 但 同时 保持 着 读 事件 被 epoll 监 控 。 在 与 认证 服务 器 间 TCP 连 接 上 ， 写 事件 的 处 理 方 
法 为 ngx_mail_ auth http_write_handler， 它 负责 把 构造 出 的 request 绥 冲 区 中 的 请 求 发 送 给 认证 
服务 器 ; 读 事 件 的 处 理 方法 为 ngx mail auth http read handler， 这 个 方法 在 接收 到 认证 服务 
器 的 响应 后 会 调用 ngx mail auth http ignore status line 方 法 首先 解析 HTTP 响 应 行 
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将 接收 客户 端 请 的 buffer 
缓冲 区 清空 


login_attempt 表 示 的 认证 
尝试 次 数 加 1 


分 配 2KB 的 内 存 池 用 于 访问 认证 服务 颖 ， 


认证 时 使 用 的 内 存 都 由 该 内 存 池 中 分 配 


建 YYngx_mail auth_http_ctx_t 
结构 体 


在 组 冲 区 request 


上 构造 发 往 认 证 服务 器 的 请 求 


回 认 证 服务 需 发 起 连接 ， 
同时 把 套 接 字 加 入 epol 和 和 定时 需 中 


现 置 下 流连 接 上 的 读 
事件 处 理 方法 


设置 与 认证 服务 器 问 连接 的 
读 事 件 处 理 方 法 


设置 与 认证 服务 器 间 连 接 的 





[检查 TCP 连接 是 否 建立 成 功 ] 





[与 认证 服务 器 间 连接 建立 成 功 ] 





调用 ngx mailauth http_write_handler 
方法 向 认证 服务 器 发 送 请 求 





[TCP 连接 暂 未 建立 成 功 ] 


| NUXPr obe. con 


图 13-6 ”启动 邮件 认证 、 向 认证 服务 器 发 起 连接 的 流程 


13.5.3 ”发 送 请 求 到 认证 服务 右 


ngx mail auth http write handler 会 发 送 request 绥 冲 区 中 的 请 求 到 认证 服务 器 ， 它 的 代码 
非常 简单 ， 如 下 所 示 。 








static void ngx mail auth http write handler(ngx event 七 *wev) { 





ssize t n, size; 


ngx connection 七 *oc; 


ngx mail session t *s; 


ngx mail auth http ctx 七 *ctx; ngx mail auth http conf 七 *ahcf; // 写 事件 上 的 








data 成 员 存 放 的 是 


Nginx 与 认证 服务 器 间 的 


TCP 连 接 


C = wev->data; 


// 连接 的 


口 由 掉 岂 有 有 和 所 掉 由 http' /wNv inuxorobe. con 





date 成 员 指 向 


ngx mail session 结构 体 


Ss = c->data; 


// 获得 描述 认证 过 程 的 


ngx mail auth http ctx 鞋 结构 体 





名 


ctx = ngx mail get module ctx(s, ngx mail auth http module); /* 如 果 向 认证 服务 器 发 送 请 求 超时 ， 则 关闭 连接 、 和 销毁 内 存 池 








这 


if (wev->timedout) { 


ngx close connection(c); 





ngx destroy pool (ctx->pool1); ngx mail session internal server error(s); return; 


Pos 和 


last 之 间 的 内 容 就 是 待 发 送 的 请 求 
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5/ 


size = ctx->request->last - ctx->request->pos; // 向 认证 服务 器 发 送 请 求 


n = ngx send(c，ctx->request->pos，size); // 如 果 发 送 失败 ， 则 关闭 连接 、 销 毁 内 存 池 ， 并 向 客户 端 发 送 错误 响应 


if (n == NGX ERROR) { 





ngx close connection(c); 





ngx destroy pool (ctx->pool1); ngx mail session internal server error(s); return; 


// 如 果 成 功 发 送 了 请 求 


request 缓 冲 区 


ctx->request->pos += n; /*size 表 示 还 需要 发 送 的 请 求 长 度 ， 


n 表 示 本 次 发 送 的 请 求 长 度 ， 当 它们 相等 时 ， 意 味 着 已 经 将 全 部 响应 发 送 到 认证 服务 器 
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if (n == Size) { 


Nginx 与 认证 服务 器 间 连 接 的 写 事 件 回调 方法 设 为 任何 事情 都 不 做 的 


ngx mail auth http dummy handler 方 法 





5 


wev->handler = ngx mail auth http dummy handler; /* 由 于 不 再 需要 发 送 请 求 ， 所 以 不 需要 再 监控 发 送 是 否 超 时 。 如 果 . 





4 
if (wev->timer set) { 
ngx del timer (wev); 1} 
// 将 写 事件 添加 到 
epoll 中 
if (ngx handle writ vent (wev, 0) != NGX OK) { 








ngx close connection(c); ngx destroy pool(ctx->pool); ngx mail session internal server error(s), 





return; 


中 INNNNNDNDD htt p: // www | i nuxpr obe. con 








// 如 果 定 时 器 中 没有 写 事 件 ， 那 么 把 它 添加 到 定时 器 中 监控 发 送 请 求 是 否 超时 


if (!wev->timer set) { 


ahcf = ngx mail get module srv confl(s, ngx mail auth http module); ngx add timer (wev, ahcf->timeout); 








} 





13.5.4 ”接收 并 解析 啊 应 





接收 并 解析 认证 服务 器 啊 应 的 方法 是 ngx mail auth http read_handler， 该 方法 要 同时 负 
责 解析 啊 应 行 和 HTTP 头 部 ， 较 为 复杂 ， 图 13-7 描 述 了 其 中 的 主要 流程 。 


图 13-6 中 所 描述 的 流程 包括 两 个 阶段 ， 首 先 接 收 到 完整 的 HTTP 响 应 行 ， 其 次 接收 到 完 
整 的 HTTP 响 应 头 部 。 这 两 个 阶段 都 并 非 一 次 调度 就 一 定 可 以 完成 的 ， 因 此 ， 当 没有 收 到 足 
ee ee lg 
吧 应 后 ， 将 可 以 得 知 认 证 是 否 通过 ， 如 果 请 求 合 法 ， 那 么 可 以 从 HTTP 啊 应 头 部 中 得 到 上 游 
邮件 服务 器 的 地 址 ， 接 着 通过 调用 ngx mail proxy init 方 法 进入 与 邮件 服务 器 交互 的 阶段 。 
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13.6 ”与 上 游 邮 件 服务 占 间 的 认证 交互 


对 于 POP3、SMTP、IMAP 来 说 ， 客 户 端 与 邮件 服务 器 之 间 最 初 的 交互 目的 都 不 太 相 
同 。 例 如 ， 对 于 POP3 和 IMAP 来 说 ， 与 邮件 服务 右 间 的 TCP 连 接 一 旦 建立 成 功 ， 邮 件 服务 器 
会 发 送 一 个 欢迎 信息 ， 接 着 客户 端 (此 时 ，Nginx 是 邮件 服务 器 的 客户 端 ) 发 送 用 户 名 ， 在 
邮件 服务 器 返回 成 功 后 再 发 送 密码 ， 等 邮件 服务 器 验证 通过 后 ， 才 会 进入 到 邮件 处 理 阶段 : 
对 于 Nginx 这 个 邮件 代理 服务 器 来 说 ， 就 是 进入 到 纯粹 地 透 传 Nginx 与 上 、 下 游 间 两 个 TCP 连 
接 之 间 的 数据 流 〈 见 13.7 节 ) 。 但 对 于 SMTP 来 说 ， 这 个 交互 过 程 又 有 所 不 同 ， 进 入 邮件 处 
理 阶 段 前 需要 交互 传输 邮件 来 源 地 址 、 邮 件 目 标 地 址 (也 就 是 From...To...) 等 信息 。 
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[检查 读 事 件 上 的 timeout 标 志 位 是 否 超 时 ] 





[接收 未 超时 , 再 检查 response 是 否 已 分 配 内 存 用 于 接收 响应 ] 










[response 缓冲 区 已 存在 ] 


[未 分 配 用 于 接收 响应 的 内 存 缓冲 区 ] 









在 response 缓冲 区 上 分 配 1KB 
的 内 存 用 于 接收 认证 服务 器 啊 应 





[接收 响应 超时 ] 


使 用 recv 方 法 在 reponse 
上 接收 响应 
[检查 recv 方 法 的 返 





回 值 ] 





[接收 到 响应 ] [失败 或 者 连接 意外 关闭 ] 


调用 ngx_mail_auth_http_ignore_status_line 





同 竹 解析 寺 响 应 行 ， 方法 解析 响应 行 
次 应 解析 HTTP 头 部 ] [检查 是 否 接收 到 完整 的 响应 行 ] 


[解析 响应 行 出 错 ] 


[解析 到 完整 响应 行 , 开始 解析 HTTP 头 部 ] 


设置 ngx_mail_auth_http_process_headers 





为 解析 HTTP 头 部 的 方法 
需 [检查 是 否 接 收 到 完整 的 HTTP 头 部 ] 







关闭 与 认证 服务 器 





间 的 连接 


调用 ngx mail_auth_http_process_headers 
解析 头 间 
[检查 是 否 接收 到 完整 HTTP 头 部 ] 


[解析 头 部 出 错 ] 








销毁 用 于 认证 邮件 的 
内 存 池 


[解析 到 完整 头 部 , 认证 成 功 ] 
[未 接收 完 头 部 ， 
等 待 下 一 次 调度 ] 


关闭 连接 ， 销 毁 内 存 池 ， 向 客 户 端 





进入 下 一 阶段 发 送 错误 





@ 
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图 137 接收 并 解析 来 自 认证 服务 器 的 响应 


无 论 如 何 ，Nginx 作 为 邮件 代理 服务 器 在 接收 到 客户 端的 请 求 ， 并 且 收 集 到 足够 进行 认 
证 的 信息 后 ， 将 会 由 Nginx 与 上 游 的 邮件 服务 器 进行 独立 的 交互 ， 直 到 邮件 服务 器 认为 可 以 
进入 到 处 理 阶段 时 ， 才 会 开始 透 传 协议 。 这 一 阶段 将 围绕 着 ngx_mail_proxy_ctx t 结 构 体 中 的 
成 员 进 行 。 下 面 以 POP3 协 议 为 例 简单 地 说 明 Nginx 是 如 何 与 邮件 服务 器 交互 的 。 








13.6.1 ngx mail proxy_ctx t 结 构 体 


ngx mail session t 结 构 体 中 的 proxy 成 员 指 向 ngx mail proxy ctx t 结 构 体 ， 该 结构 体 含有 
Nginx 与 上 游 间 的 连接 upstream， 以 及 与 上 游 通 信 时 接收 上 游 TCP 消 恩 的 缓冲 区 ， 如 下 所 示 。 





typedef struct { 


// 与 上 游 邮 件 服务 器 间 的 连接 


ngx peer connection t upstream; 


/* 用 于 缓存 上 、 下 游 间 
TCP 消 息 的 内 存 缓冲 区 ， 内 存 大 小 由 
nginx.conf 文 件 中 的 


proxy_buffer 配 置 项 决定 


中 INNNNNDNDD htt p: // www | i nuxorobe con 





ngx buf 七 *buffer; 


} ngx mail proxy ctx t; 








er 注意 ”proxy 成 员 最 初 也 是 NUIL 空 指针 ， 直 到 调用 ngx_mail_proxy_init 方 法 后 才 会 为 
ptoxy 指 针 分 配 内 存 。 


13.6.2 ”加 上 游 邮件 服务 器 发 起 连接 


根据 ngx_mail_proxy_init 方 法 可 以 局 动 Nginx 与 上 游 邮 件 服务 右 间 的 交互 ， 下 面 看 一 下 该 
方法 主要 做 了 哪些 工作 。 





void ngx mail proxy init (ngx mail _ session t s, ngx addr t Peer) { 


// 创建 


ngx mail proxy ctx 七 结构 体 





ngx mail proxy ctx t xp = ngx pcalloc( s->connection->pool, sizeof (ngx mail proxy ctx t)); if (p == NULL) { 











ngx mail session internal server error(s); return; 


// 注意 ,之 前 的 


TinNNNinNnnn http://wWwWw linuxorobe.con 





proxy 成 员 指 向 的 是 


NULL 空 指针 


s->proxy = p; 


// 向 上 游 的 邮件 服务 器 发 起 无 阻塞 的 


TCP 连 接 


ngx int t rc = ngx event connect Peer (&p->upstream); … 


/* 需 要 监控 接收 邮件 服务 器 的 响应 是 否 超时 ， 于 是 把 与 上 游 间 连接 的 读 事件 添加 到 定时 器 中 
*/ 


ngx adqd timer (p->upstream.connection->read, cscf->timeout); // 设置 连接 的 


data 成 员 指 向 
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ngx _ mail session 七 结构 体 


p->upstream.connection->data = s; /* 设 置 





Nginx 与 客户 端 间 连 接 读 事件 的 回调 方法 为 不 会 读 取 内 容 的 


ngx mail proxy block read 方 法 ， 因 为 当前 阶段 








Nginx 不 会 与 客户 端 交互 


*/ 


s->connection->read->handler = ngx mail proxy block read; /* 设 置 











Nginx 与 上 游 间 的 连接 写 事件 回调 方法 为 什么 事 都 不 做 的 


ngx mail proxy dummy handler 方 法 ， 这 意味 着 接 下 来 向 上 游 发 送 





TCP 流 时 ， 将 不 再 通过 





epoll 这 个 事件 框架 来 调度 ， 下 一 节 将 看 到 实际 的 用 法 


4 
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p->upstream.connection->write->handler = ngx mail proxy dummy handler; /* 建 立 





Nginx 与 邮件 服务 器 间 的 内 存 缓冲 区 ， 缓 冲 区 大 小 由 


nginx.conf 文 件 中 的 


proxy_buffer 配 置 项 决定 
*/ 


Ss->proxy->buffer = ngx create temp buf(s->connection->pool, pcf->buffer size); // 注意 , 设置 


out 为 空 ， 表 示 将 不 会 再 通过 


OUt 向 客户 端 发 送 响 应 


s->out.len = 0; 


// 根据 用 户 请 求 的 协议 设置 实际 的 邮件 认证 方法 


Switch (s->protocol) { 
case NGX MAIL POP3 PROTOCOL: 


// 设置 
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POP3 协 议 进 行 邮 件 交 互 认证 的 方法 


p->upstream.connection->read->handler = ngx mail proxy Pop3 handler; s->mail state = ngx pop3 start; brt 





case NGX MAIL IMAP PROTOCOL: 


// 设置 


IMAP 进 行 邮 件 交 互 认证 的 方法 


p->upstream.connection->read->handler = ngx mail proxy imap handler; s->mail state = ngx imap start; brt 





default: /* NGX MAIL SMTP PROTOCOL */ 


// 设置 


SMTP 进 行 邮件 交互 认证 的 方法 


p->upstream.connection->read->handler = ngx mail proxy smtp handler; s->mail state = ngx smtp start; brt 








可 以 看 到 ， 其 中 最 重要 的 工作 在 于 分 配 了 ngx_mail_proxy_ctx t 结 构 体 ， 并 为 成 员 buffer 分 


配 了 人 me | 局 占 ee J er 最 后 





针对 不 同 的 邮件 协议 分 别 设置 了 ngx mail proxy pop3 handler、ngx mail proxy imap handler 
或 者 ngx mail proxy_smtp_handler 方 法 ， 用 于 Nginx 与 上 游 邮 件 服务 器 间 的 交互 。 


13.6.3 ”与 邮件 服务 器 认证 交互 的 过 程 





由 于 每 种 协议 的 交互 过 程 都 不 相同 ， 因 此 下 面 仅 以 POP3 协 议 为 例 简单 地 说 明 这 一 过 程 
古 如 何 实现 的 ， 如 下 所 示 。 





static voidngx mail proxy pop3 handler (ngx event t *rev) { 





u char *p; 


ngx int t rc; 


ngx Connection 七 *oc; 


ngx mail session t *s; 


ngx mail proxy conf 七 *pcf; 





// line 将 会 保存 发 往 上 游 邮件 服务 器 的 消息 


ngx str t line; 


// 获取 


Nginx 与 上 游 间 的 连接 


C = rev->data; 


站 由 掉 岂 有 所 和 所 掉 由 http' /wNv inuxorobe. con 





// 获得 


ngx _ mail _ session 七 结构 体 


Ss = c->data; 


// 如 果 读 取 上 游 邮 件 服务 器 响应 超时 ， 则 向 客户 端 发 送 错误 响应 


if (rev->timedout) { 


c->timedout = 1; 





ngx mail proxy internal server error(s); return; 


// 读 取 上 游 邮 件 服务 器 发 来 的 响应 到 


buffer 缓 冲 区 中 


rc = ngx mail proxy read response(s，0); // 还 需要 继续 接收 邮件 服务 器 的 消息 ， 期 待 下 一 次 的 调度 





if (rc == NGX AGAIN) { 


return; 
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// 消息 不 合法 ， 或 者 邮件 服务 器 没有 验证 通过 ， 则 返回 错误 给 客户 端 


if (rc == NGX ERROR) { 





ngx mail proxy upstream error(s); return; 


Switch (s->mail state) { 


case ngx pop3 start: 


// 构造 发 送 给 邮件 服务 器 的 用 户 信息 





line.len = sizeof ("USER ") - 1 + s->login.len + 2; line.data = ngx pnalloc(c->pool, line.len); if (line 





ngx mail proxy internal server error(s); return; 








p = ngx cpymem(line.data, "USER ", sizeof ("USER ") - 1); p = ngx cpymem(p, s->login.data, s->login.1len) 


s->mail state = ngx pop3 user; break; 


Case ngx pop3 user: 


// 构造 发 送 给 邮件 服务 器 的 密码 信息 
line.len = sizeof ("PASS ") - 1 + s->passwd.len + 2; line.data = ngx pnalloc(c->pool, line.len); if (lim 
ngx mail proxy internal server error(s); return; 
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p = ngx cpymem(line.data, "PASS "，Sizeof("PASS ") - 1); p = ngx cpymem(p, s->passwd.data, S->passwdq.1el 


s->mail state = ngx pop3 passwd; break; 


case ngx pop3 passwd: 


/* 在 收 到 服务 器 返回 的 密码 验证 通过 信息 后 ， 将 


Nginx 与 下 游客 户 端 间 、 


Nginx 与 上 游 邮件 服务 器 间 的 


TCP 连 接 上 读 





/ 写 事件 的 回调 方法 都 设置 为 


ngx mail proxy handler 方 法 (参见 


13.7 种 》 


s->connection->read->handler = ngx mail proxy handler; s->connection->write->handler = ngx mail proxy h: 


丫 熙 攻 伴 竺 除 由 有 由 有 由 http:/ /WwW | inuxorobe. con 





TCP 阶 段 


ngx mail proxy handler(s->connection->write); return; 


default: 


#if (NGX SUPPRESS WARN) 





ngx_ str null(&line); 


#endif 


break; 


/* 向 上 游 的 邮件 服务 器 发 送 验 证 信息 。 注 意 ， 这 里 向 邮件 服务 器 发 送 


TCP 流 与 本 书 的 其 他 章节 都 不 相同 ， 它 不 再 通过 


epoll 检 测 到 








TCP 连 接 上 出 现 可 写 事件 而 触发 。 事 实 上 ， 它 是 由 连接 上 出 现 的 可 读 事件 触发 的 ， 因 为 读 取 到 了 邮件 服务 器 的 消息 ， 才 向 邮件 服务 器 发 送 消 息 。 之 所 


TCP 消 息 包 都 非常 短小 


*/ 
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if (c->sendl(c, line.data, line.len) < (ssize t) line.len) { 





ngx mail proxy internal server error(s); return; 


buffer 缓 冲 区 


Ss->proxy->buffer->pos = s->proxy->buffer->start; s->proxy->buffer->last = s->proxy->buffer->start; } 





一 旦 收 到 用 户 名 、 和 密码 验证 通过 的 消息 ， 就 会 由 ngx_mail proxy_handler 方 法 进入 透 传 
上 、 下 游 TCP 流 的 阶段 。 
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13.7 透 传 上 游 邮 件 服务 器 与 客户 端 间 的 流 








ngx_mail_proxy_handler 方 法 同时 负责 处 理 上 、 下 游 间 的 四 个 事件 (两 个 读 事 件 、 两 个 写 
事件 ) 。 该 方法 将 完全 实现 上 、 下 游 邮 件 协议 之 间 的 透 传 ， 本 市 将 通过 直接 研究 这 个 方法 来 
看 看 如 何 用 固定 大 小 的 缓存 实现 透 传 功能 《有些 类 似 于 upstream 机 制 转发 啊 应 时 仅 用 了 固定 
缓存 的 模式 ， 但 upstream 机 制 只 是 单 癌 的 转 有 发 ， 而 透 传 则 是 双 同 的 转 及 ) 。 


下 面 先 来 介绍 双 癌 转发 TCP 流 时 将 会 用 到 的 两 个 缓冲 区 : ngx_mail_session t 中 的 buffer 绥 
种 区 用 于 转发 下 游客 户 端的 消息 给 上 游 的 邮件 服务 器 ， 而 ngx_mail proxy_ctx t 中 的 buffer 绥 冲 
区 则 用 于 转发 上 游 邮 件 服务 器 的 消息 给 下 游 的 客户 端 。 在 这 两 个 ngx_buf t 烘 型 的 缓冲 区 中 ， 
pos 指 针 指 向 待 转发 消息 的 起 始 地 址 ， 而 last 指 针 指 向 最 后 一 次 接收 到 的 消息 的 末尾 。 当 pos 
等 于 last 时 ， 意 味 着 全 部 缓存 消息 都 转发 完了 ， 这 时 会 把 pos 和 1last 都 指 癌 缓冲 区 的 首部 start 指 
针 ， 相 当 于 清空 缓冲 区 以 便 再 次 复 用 完整 的 缓冲 区 。 相 关 代 码 如 下 所 示 。 

















static void ngx mail proxy handler (ngx event 七 *ev) { 





// 当前 的 动作 ， 用 于 记录 日 志 


char *action,， recv action，send action; /*size 变 量具 有 两 种 含义 : 在 读 取 消息 时 ， 
size 表 示 
recv 方 法 中 空闲 缓冲 区 的 大 小 ， 在 发 送 消 息 时 ， 表 示 将 要 发 送 的 消息 长 度 


4 
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Size t size; 


// send 或 者 


recv 方 法 的 返回 值 


SSize.t ny 


// b 表 示 用 于 接收 


TCP 消 息 的 缓冲 区 ， 或 者 指向 用 于 发 送 消息 的 缓冲 区 


ngx buf 七 *b; 


// do_write 标 志 位 决定 本 次 到 底 是 发 送 还 是 接收 


TCP 消 息 


ngx uint t do write; 


/* 每 次 透 传 


TCP， 上 、 下 游 的 客户 端 与 邮件 服务 器 之 间 必 然 有 一 个 负责 提供 消息 ， 另 一 个 负责 接收 


口 由 掉 所 有 所 和 所 掉 由 http' /wNv inuxorobe. con 





Nginx 转 发 的 消息 。 


src 用 来 表示 


Nginx 与 提供 消息 一 方 之 间 的 连接 ， 而 


dst 表 示 


Nginx 与 接收 消息 一 方 之 间 的 连接 


4 


ngx connection 七 *c, src, dst; ngx mail session t *s; 


ngx mail proxy conf 七 *pcf; 





/* 注 意 ， 事 件 


ev 既 可 能 属于 


Nginx 与 下 游 间 的 连接 ， 也 有 可 能 属于 


Nginx 与 上 游 间 的 连接 ， 此 时 无 法 判断 连接 


c 究 竟 是 来 自 于 上 游 还 是 下 游 


口 岂 所 岂 有 有 和 所 掉 由 http' /wNv inuxorobe. con 





C= ev->data; 


/* 无 论 是 在 上 游 连接 还 是 下 游 连接 上 ， 


ngx_connection 七 结构 体 的 


data 成 员 都 将 指向 


ngx mail _ session 七 结构 体 


4 


Ss = c->data; 


// 无 论 上 、 下 游 ， 只 要 接收 或 者 发 送 消息 出 现 了 超时 ， 都 需要 终止 透 传 操作 


if (ev->timedout) { 


// ngx mail] proxy close session 方 法 会 同时 关闭 上 、 下 游 的 





TCP 连 接 
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ngx mail proxy close session(s); return; 





/* 注 意 ， 


ngx mail session 七 结构 体 中 的 


connection 成 员 一 定 指向 


Nginx 与 下 游客 户 端 间 的 


TCP 连 接 


人 


if (Cc == s->connection) { 





// 以 下 分 支 意 味 着 收 到 了 下 游 连接 上 的 事件 (无论 是 可 读 事 件 还 是 可 写 事件 ) 


if (ev->write) { 


/* 当 下 游 可 写 事件 被 触发 时 ， 意 味 着 本 次 


Nginx 将 负责 把 接收 自 上 游 的 缓存 消息 发 送 给 下 游 


Ry 
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SrC 来 源 连 接 为 上 游 连 接 


src = Ss->proxy->upstream.connection; // 设 


dst 目 标 连接 为 下 游 连接 


// 设置 用 于 向 下 游 发 送 的 消息 缓冲 区 


D = s->proxy->buffer; } else { 


/* 当 下 游 可 读 事件 被 触发 时 ， 意 味 着 本 次 


Nginx 将 负责 先 读 取 下 游 的 响应 到 缓存 中 ， 为 下 一 步 转发 给 上 游 做 准备 


*/ 


recv action = "proxying and reading from client"; send action 


SLC 来 源 连 接 为 下 游 连接 


"proxying and sending to upstream" 
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SC 二 CC 


// 设 


dst 目 标 连接 为 上 游 连接 


dst = s->proxy->upstream.connection; // 设置 用 于 接收 下 游 消 息 的 缓冲 区 


b = s->buffer; 


} else { 





// 以 下 分 支 意 味 着 收 到 了 上 游 连接 上 的 事件 


if (ev->write) { 


/* 当 上 游 可 写 事件 被 触发 时 ， 意 味 着 本 次 


Nginx 将 负责 把 接收 自 下 游 的 缓存 消息 发 送 给 上 游 
4 


recv action = "proxying and reading from client"; send action = "proxying and sending to upstream"; 


SLC 来 源 连 接 为 下 游 连接 
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src = Ss->connection; // 设 


dst 来 源 连接 为 上 游 连接 


// 设置 用 于 向 上 游 发 送 的 消息 缓冲 区 


b = s->buffer; 


} else { 


/* 当 上 游 可 读 事 件 被 触发 时 ， 意 味 着 本 次 


Nginx 将 负责 接收 上 游 的 消息 到 缓存 中 ， 为 下 一 步 把 这 个 消息 转发 给 下 游 做 准备 


recv action = "proxying and reading from upstream"; send action 


SrC 来 源 连 接 为 上 游 连 接 


BLC 


*/ 


"proxying and sending to client"; 
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// 设 


dst 来 源 连接 为 下 游 连 接 


dst = s->connection; // 设置 用 于 接收 上 游 消息 的 缓冲 区 


b = s->proxy->buffer; } 





// 当前 触发 事件 的 


write 标 志 位 将 决定 


do _write 本 次 是 发 送 消息 还 是 接收 消息 


do write = ev->write 1 : 0; /* 进 入 向 


dst 连 接 发 送 消息 或 者 由 





src 连 接 上 接收 消息 的 循环 ， 直 到 套 接 字 上 和 暂 无 可 读 或 可 写 事件 时 才 退 出 


G4 
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if (do _ write) { 


// 如 果 本 次 将 发 送 


TCP 消 息 ， 那 么 首先 计算 出 要 发 送 的 消息 长 度 


size = b->last - b->pos; // 检查 需要 发 送 的 消息 长 度 


Size 是 和 否 大 于 


0， 以 及 目标 连接 当前 是 否 可 写 


if (size && dst->write->ready) { 


c->1og->action = senq action; // 调用 


send 方 法 向 


dst 目 标 连 接 上 发 送 


TCP 消 息 
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n = dst->send(dst, b->pos, size); if (n == NGX ERROR) { 





// 发 送 错 误 时 直接 结束 请 求 


ngx mail proxy close session(s); return; 





if£. (Ni SO0) { 


// 更 新 消息 缓冲 区 


b->pos += n;// 如 果 缓 冲 区 中 的 消息 全 部 发 送 完 ， 则 清空 缓冲 区 以 复 用 


if (b->pos == pb->last) { 


b->pos = b->start; b->last = b->start; } 


// 为 下 面 读 取 


TCP 消 息 做 准备 ， 先 计算 接收 缓冲 区 上 的 空闲 空间 大 小 
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size = b->end - b->last; // 检查 空闲 缓冲 区 大 小 是 否 大 于 


0， 以 及 源 连接 上 当前 是 否 可 读 


if (size && src->read->ready) { 


c->1og->action = recv action; // 调用 


recv 方 法 由 


Src 源 连接 上 接收 


TCP 消 息 


n = src->recv(src，b->last，size); // 如 果 没 有 读 取 到 内 容 ， 或 者 对 方 主动 关闭 了 


TCP 连 接 ， 则 跳出 循环 


if ‘(ri ==, NGX AGAIN 小 | m== 0), 1{ 


break; 
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if (n> 0) { 


// 如 果 读 取 到 了 消息 ， 则 应 试图 在 本 次 


ngx mail proxy handler 方 法 的 执行 中 将 它 立即 发 送出 去 


7/ 


do Write, .1: 


// 更 新 消息 缓冲 区 


b->last += n; 


// 重新 执行 循环 ， 检 查 是 否 可 以 立即 转发 出 去 





continue; 


if (n == NGX ERROR) { 





src->read->eof = 1; } 


break; 


c->1og->action = "proxying"; // 如 果 上 、 下 游 间 的 连接 中 断 ， 则 结束 透 传 流程 
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if ((s->connection->read->eof && s->buffer->pos == s->buffer->last) || (sS->proxy->upstream.connection->read- 


action = c->l0og->action; c->log->action = NULL; c->log->action = action; ngx mail proxy Close sessionl(s, 





// 下 面 将 会 把 


Nginx 与 上 、 下 游 


TCP 连 接 上 的 


4 个 读 


/ 写 事件 再 次 添加 到 








epoll 中 监控 
if (ngx handle write event (dst->write, 0) != NGX OK) { 
ngx mail proxy close session(s); return; 





(dst->read, != NGX OK) 
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ngx mail proxy close session(s); return; 





if (ngx handle write event (src->write, 0) != NGX OK) { 





ngx mail proxy close session(s); return; 





if (ngx handle read event (src->read, 0) != NGX OK) { 


ngx mail proxy close session(s); return; 





/* 接 收 下 游客 户 端的 消息 时 还 是 需要 检查 超时 的 ， 防 止 “ 僵 死 ” 的 客户 端 占用 


Nginx 服 务 器 资源 


G4 


if (Cc == s->connection) { 


pcf = ngx mail get module srv confl(s, ngx mail proxy module); ngx add timer(c->read, pcf->timeout); } 











可 以 看 到 ，ngx_mail proxy_handler 方 法 很 简单 ， 不 过 百 行 代码 就 完成 了 透 传 功能 。 至 于 在 这 一 阶段 中 客户 端 究 竟 与 
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13.8 小结 


本 章 介 绍 了 Nginx 是 如 何 设计 并 实现 官方 提供 的 邮件 代理 服务 器 的 ， 当 需要 文 持 新 的 邮 
件 协 议 时 ， 类 似 于 HTTP 框 架 的 邮件 框架 可 以 较 容易 地 集成 新 的 邮件 模块 。 邮 件 框架 和 HTTP 
框架 都 是 应 用 事件 框架 很 好 的 例子 。 如 果 用 户 更 希望 Nginx 作 为 基于 TCP 的 其 他 应 用 层 协 议 服 
务 器 ， 而 不 是 局 限于 Web 服 务 妖 ， 那 么 可 以 对 比 和 参考 这 两 个 框架 ， 编 写 一 种 新 的 Nginx 模 
块 ， 从 而 充分 利用 Nginx 底 层 的 强大 设计 功能 。 
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第 14 草 ”进程 间 的 通信 机 制 


本 章 并 不 是 说 明 Linux 下 有 哪些 进程 通信 方式 ， 而 是 为 了 说 明 Nginx 选 择 了 哪些 方式 来 同 
步 master 进 程 和 多 个 worker 进 程 间 的 数据 ，Nsginx 框 架 是 怎样 重新 封装 了 这 些 进程 间 通 信 方 式 
的 ， 以 及 在 开发 Nginx 模 块 时 应 该 怎样 使 用 这 些 封装 过 的 方法 。 


Nginx 由 一 个 master 进 程 和 多 个 worker 进 程 组 成 ， 但 master 进 程 或 者 worker 进 程 中 并 不 会 
再 创建 线程 (Nginx 的 多 线程 机 制 一 直 停 留 在 测试 状态 ， 虽 然 不 排除 未 来 Nginx 可 能 发 布 支持 
多 线程 版 本 的 可 能 性 ， 但 直到 目前 最 新 的 1.2.x 版 本 仍然 未 支持 多 线程 ) ， 因 此 ， 本 章 的 内 容 
不 会 涉及 线程 间 的 通信 。 
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14.1 概述 





Linux 提 供 了 多 种 进程 间 传递 消息 的 方式 ， 如 共享 内 存 、 套 接 字 、 管 道 、 消 息 队 列 、 信 
号 等 ， 每 种 方式 都 有 其 优 缺 点 ， 而 Nginx 框 架 使 用 了 3 种 传递 消息 传递 方式 : 共享 内 存 、 套 接 
字 、 信 号 。 在 14.2 节 将 会 介绍 Nginx 是 怎样 使 用 、 封 装 共享 内 存 的 ; 在 14.4 节 会 介绍 进程 间 怎 
样 使 用 套 接 字 通信 ， 以 及 如 何 使 用 基于 套 接 字 封 装 的 Nginx 频 道 ; 在 14.5 节 中 将 会 介绍 进程 间 
怎样 通过 发 送 、 接 收 信号 来 传递 消息 。 








在 多 个 进程 访问 共 阐 资源 时 ， 还 需要 提供 一 种 机 制 使 各 个 进程 有 序 、 安 全 地 访问 资源 ， 
避免 并 发 访问 带 来 的 未 知 结果 。Nginx 主 要 使 用 了 3 种 同步 方式 : 原子 操作 、 信 号 量 、 文 件 
锁 。 在 14.3 市 将 会 介绍 在 Nginx 中 原子 操作 是 怎样 实现 的 ， 同 时 还 会 介绍 基于 原子 变量 实现 的 
目 旋 锁 ;在 14.6 贡 将 会 介绍 信号 量 ， 与 “信号 ”不同 的 是 ， 中 文 译名 仅 有 一 字 之 产 的 “信号 
量 ” 其 实 是 用 于 同步 代码 段 的 执行 的 ， 在 14.7 市 将 会 介绍 文件 锁 。 




















由 于 Nginx 的 每 个 worker 进 程 都 会 同时 处 理 干 万 个 请 求 ， 所 以 处 理 任 何 一 个 请 求 时 都 不 
应 该 阻 豆 当前 进程 处 理 后续 的 其 他 请 求 。 例 如 ， 不 要 随意 地 使 用 信号 量 互 斥 锁 ， 这 会 使 得 
worker 进 程 在 得 不 到 锁 时 进入 睡眠 状态 ， 从 而 导致 这 个 worker 进 程 上 的 其 他 请 求 被 “ 饿 死 ”。 
鉴于 此 ，Nginx 使 用 原子 操作 、 信 号 量 和 文件 锁 实 现 了 一 套 ngx_shmtx ft 互 斥 锁 ， 当 操作 系统 
文 持 原子 操作 时 ngx_shmtx t 就 由 原子 变量 实现 ， 盏 则 将 由 文件 锁 来 实现 。 顾 名 思 义 ， 
ngx_shmtx t 锁 是 可 以 在 共 侍 内 存 上 使 用 的 ， 它 是 Nginx 中 最 常见 的 锁 。 
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共 诗 内 存 是 Linux 下 提供 的 最 基本 的 进程 间 通 信 方 法 ， 它 通过 mmap 或 者 shmget 系 统 调 用 
在 内 存 中 创建 了 一 块 连续 的 线性 地 址 空间 ， 而 通过 munmap 或 者 shmdt 系 统 调用 可 以 释放 这 块 
内 存 。 使 用 共 译 内 存 的 好 处 是 当 多 个 进程 使 用 同一 块 共 圣 内 存 时 ， 在 任何 一 个 进程 修改 了 共 
译 内 存 中 的 内 容 后 ， 其 他 进程 通过 访问 这 段 共 至 内 存 都 能 够 得 到 修改 后 的 内 容 。 





@ 注意 ”虽然 mmap 可 以 以 磁盘 文件 的 方式 映射 共享 内 存 ， 但 在 Nginx 封 装 的 共享 内 存 
操作 方法 中 是 没有 使 用 到 映射 文件 功能 的 


Nginx 定 义 了 ngx_shm t 结 构 体 ， 用 于 描述 一 块 共 享 内 存 ， 代 人 码 如 下 所 示 。 





typedef struct { 


// 指向 共享 内 存 的 起 始 地 址 


u char *addr; 


// 共享 内 存 的 长 度 


size t size; 


// 这 块 共享 内 存 的 名 称 


ngx_ str t name; 
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ngx 1og 七 对 象 


ngx log 七 *1og7 


// 表示 共享 内 存 是 否 已 经 分 配 过 的 标志 位 ， 为 


1 时 表示 已 经 存在 


ngx uint t exists; 


} ngx shm t; 





操作 ngx_shm it 结构 体 的 方法 有 以 下 两 个 : ngx shm alloc 用 于 分 配 新 的 共享 内 存 ， 而 
ngx shm free 用 于 释放 已 经 存在 的 共享 内 存 。 在 描述 这 两 个 方法 前 ， 先 以 mmap 为 例 说 明 Linux 
是 怎样 回应 用 程序 提供 共享 内 存 的 ， 如 下 所 示 。 





void mmap (void start, size t length, int prot, int flags, int fd, off t offset); 


mmap 可 以 将 磁盘 文件 映射 到 内 存 中 ， 直 接 操作 内 存 时 Linux 内 核 将 负责 同步 内 存 和 磁盘 
文件 中 的 数据 ， 季 参数 就 指向 需要 同步 的 磁盘 文件 ， 而 offset 则 代表 从 文件 的 这 个 偏 移 量 处 开 
始 共享 ， 当 然 Nginx 没 有 使 用 这 一 特性 。 当 flags 参 数 中 加 入 MAP_ANON 或 者 
MAP ANONYMOUS 参数 时 表示 不 使 用 文件 映射 方式 ， 这 时 包 和 ofRet 参 数 就 没有 意义 ， 也 不 
需要 传递 了 ， 此 时 的 mmap 方 法 和 ngx_shm alloc 的 功能 几乎 完全 相同 。length 参 数 就 是 将 要 在 


内 存 中 开辟 的 线性 地 址 空间 大 小 ， 而 prot 参 数 则 是 操作 这 段 共享 内 存 的 方式 〈 如 只 读 或 者 可 
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读 可 写 ) ，start 参 数 说 明和 希望 的 共 吾 内 存 起 始 映射 地 址 ， 当 然 ， 通 常 都 会 把 start 设 为 NULL 空 
指针 。 


先 来 看 看 如 何 使 用 mmap 实 现 ngx shm alloc 方 法 ， 代 码 如 下 。 





ngx int t ngx shm alloc(ngx shm t *shm) { 





// 开辟 一 块 


shm->size 大 小 且 可 以 读 


/ 写 的 共享 内 存 ， 内 存 首 地 址 存放 在 


adqdr 中 


shm->addr = (u char *) mmap (NULL, shm->size, PROT READ|PROT WRITE, MAP ANON|MAP SHARED, -1, 0); if (shm->ad 














return NGX ERROR; 


return NGX OK; 





这 里 不 再 介绍 shmget 方 法 申请 共 诗 内 存 的 方式 ， 它 与 上 述 代码 相似 。 


当 不 再 使 用 共享 内 存 时 ， 需 要 调用 munmap 或 者 shmdt 来 释放 共享 内 存 ， 这 里 还 是 以 与 
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mmap 配 对 的 munmap 为 例 来 说 明 。 





int munmap (void *start, size t length); 





其 中 ，start 参 数 指向 共享 内 存 的 首 地 址 ， 而 length 参 数 表示 这 上 段 共享 内 存 的 长 度 。 下 面 看 
看 ngx shm free 方 法 是 怎样 通过 munmap 来 释放 共享 内 存 的 。 





void ngx shm free(ngx shm 七 xsShm) { 


// 使 用 


ngx_Shm 七 中 的 


addqr 和 


size 参 数 调用 


munmap 释 放 共 享 内 存 即 可 


if (munmap( (void *) shm->addr, shm->size) == -1) { 


ngx log error (NGX LOG ALERT, shm->log, ngx errno, "munmap (%$p, %uz) failed", shm->addr, shm->size); } 











Nginx 各 进程 间 共享 数据 的 主要 方式 就 是 使 用 共享 内 存 〈 在 使 用 共享 内 存 时 ，Nginx 一 般 
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是 由 master 进 程 创建 ， 在 master 进 程 fork 出 worker 子 进程 后 ， 所 有 的 进程 开始 使 用 这 块 内 存 中 
的 数据 ) 。 在 开发 Nginx 模 块 时 如 果 需 要 使 用 它 ， 不 妨 用 Nginx 已 经 封装 好 的 ngx_shm_alloc 方 
法 和 ngx_shm free 方 法 ， 它 们 有 3 种 实现 (不 映射 文件 使 用 mmap 分 配 共享 内 存 、 以 /dev/zero 文 
件 使 用 mmap 映 射 共 享 内 存 、 用 shmset 调 用 来 分 配 共享 内 存 ) ， 对 于 Nginx 的 跨 平台 特性 考虑 
得 很 周到 。 下 面 以 一 个 统计 HTTP 框 架 连 接 状 况 的 例子 来 说 明 共 享 内 存 的 用 法 。 





作为 Web 服 务 器 ，Nginx 具 有 统计 整个 服务 器 中 HTTP 连 接 状 况 的 功能 (不 是 某 一 个 Nginx 
worker 进 程 的 状况 ， 而 是 所 有 worker 进 程 连接 状况 的 总 和 〉 。 例 如 ， 可 以 用 于 统计 某 一 时 刻 
下 Nginx 已 经 处 理 过 的 连接 状况 。 下 面 定 义 的 6 个 原子 变量 就 是 用 于 统计 
ngx_http_stub_status_module 模 块 连接 状况 的 ， 如 下 所 示 。 





// 已 经 建立 成 功 过 的 


TCP 连 接 数 


ngx atomic t ngx_ stat accepted0; 


ngx atomic 七 *ngx stat accepted = &ngx stat accepted0; /* 已 经 从 


ngx_cycle 七 核心 结构 体 的 


free_connections 连 接 池 中 获取 到 


ngx_connection 七 对 象 的 活跃 连接 数 
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ngx atomic t ngx stat active0; 


ngx atomic 七 *ngx stat active = &ngx stat active0; /* 连 接 建 立成 功 且 获取 到 


ngx connection 七 结构 体 后 ， 已 经 分 配 过 内 存 池 ， 并 且 在 表示 初始 化 了 读 





/ 写 事 件 后 的 连接 数 
ngx atomic t ngx stat handled0; 


ngx atomic 七 *ngx stat handled = &ngx stat handled0; // 已 经 由 


HTTP 模 块 处 理 过 的 连接 数 


ngx atomic t ngx stat requests0; 


ngx atomic t *ngx stat requests = &ngx stat requests0; // 正在 接收 


TCP 流 的 连接 数 


ngx atomic t ngx stat reading0; 


ngx atomic t *ngx stat reading = &ngx stat reading0; // 正在 发 送 


TiNNNnNnnn http://wWwWw linuxorobe.con 





TCP 流 的 连接 数 


ngx atomic t ngx stat writing0; 


ngx atomic 七 *ngx stat writing = &ngx stat writing0， 











ngx_atomic t 原 子 变 量 将 会 在 14.3 节 详细 介绍 ， 本 节 仪 关注 这 6 个 原子 变量 是 如 何 使 用 共 
享 内 存在 多 个 worker 进 程 中 使 用 这 些 统计 变量 的 。 





size 七 size; cl; 
ngx shm t shm; 


/* 计 算出 需要 使 用 的 共享 内 存 的 大 小 。 为 什么 每 个 统计 成 员 需 要 使 用 


128 字 节 呢 ?这 似乎 太 大 了 ， 看 上 去 ， 每 个 


ngx_atomic 七 原子 变量 最 多 需要 


Nginx 充 分 考虑 了 


CPU 的 二 级 缓存 。 在 目前 许多 
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CPU 架构 下 缓存 行 的 大 小 都 是 


128 字 节 ， 而 下 面 需要 统计 的 变量 都 是 访问 非常 频繁 的 成 员 ， 同 时 它们 占用 的 内 存 又 非常 少 ， 所 以 采用 了 每 个 成 员 都 使 用 


128 字 节 存 放 的 形式 ， 这 样 速度 更 快 


cl = 128; 
size = cl 
省 二 
GL 
XA/ -案头 了 


/* ngx accept mutex */ 


4 


/* ngx connection counter */ 


/* ngx temp number */ 


NGX_STAT _STUB 宏 后 才 会 统计 上 述 


6 个 原子 变量 


#if (NGX STAT STUB) 


size += cl 


+ Cl 


+ Cl 


/* ngx stat accepted */ 


/* ngx_ stat handled */ 


/* ngx stat requests */ 


[| Th El [| [Fjek jthd|aft|v| |/ 





htt po: // WW | 1 Nuxpor obe. con 


再 过 于 /* ngx stat reading */ 


+ cl; /* ngx stat writing */ 


#endif 


// 初始 化 描述 共享 内 存 的 


ngx_shm 结构 体 


shm.size = size; 


shm.name.len = sizeof ("nginx shared zone"); shm.name.data = (u char *) "nginx shared zone"; shm.1og = Cycle 


// 开辟 一 块 共享 内 存 ， 共 享 内 存 的 大 小 为 


shm.size 


if (ngx shm alloc(&shm) != NGX OK) { 





return NGX ERROR; 


// 共享 内 存 的 首 地 址 就 在 


shm.addr 成 员 中 


shared = shm.addr; 
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// 原子 变量 类 型 的 


accept 锁 使 用 了 


128 字 节 的 共享 内 存 





ngx accept mutex ptr = (ngx _ atomic t *) shared; // ngx accept mutex 就 是 负载 均衡 锁 ， 





Spin 值 为 


-1 则 是 告诉 


Nginx 这 把 锁 不 可 以 使 进程 进入 睡眠 状态 ， 详 见 


14.8 节 
4 


ngx accept mutex.spin = (ngx uint 七 ) -1; /x* 原 子 变 量 类 型 的 


ngx_connection _ counter 将 统计 所 有 建立 过 的 连接 数 (包括 主动 发 起 的 连接 ) 
*/ 


ngx connection counter = (ngx atomic t *) (shared + 1 * cl) #if (NGX STAT STUB) 


厅 站 站 有 有 下放 Ptto' // waw li nuxporobe. con 





// 依次 初始 化 需要 统计 的 


6 个 原子 变量 ， 也 就 是 使 用 共享 内 存 作 为 原子 变量 


ngx Stat accepted = (ngx atomic t *) (shared + 3 * cl); ngx stat handled = (ngx atomic t *) (shared + 4 * C- 





这 6 个 统计 变量 在 初始 化 后 ， 在 处 理 请 求 的 流程 中 由 于 其 意义 不 同 ， 所 以 其 值 会 有 所 变 
化 。 例 如 ， 在 HTTP 框 架 中 ， 刚 开始 接收 客户 端的 HTTP 请 求 时 使 用 的 是 ngx_http_init_request 
方法 ， 在 这 个 方法 中 就 会 将 ngx_stat_reading 统 计 变量 加 1， 表 示 正 处 于 接收 用 户 请 求 的 连接 数 
加 1， 如 下 所 示 。 














(void) ngx atomic fetch add(ngx stat reading, 1); 








而 当 读 取 完 请 求 时 ， 如 在 ngx http process_ request 方法 中 ， 开 始 处 理 用 户 请 求 〈 不 再 接 
收 TCP 消 息 ) ， 这 时 会 把 ngx stat reading 统 计 变 量 减 1， 如 下 所 示 。 





(void) ngx atomic fetch add(ngx stat reading, -1); 








这 6 个 统计 变量 都 是 在 关键 的 流程 中 进行 维护 的 ， 每 个 worker 进 程 修改 的 都 是 共享 内 存 
中 的 统计 变量 ， 它 们 对 于 整个 Nginx 服 务 来 说 是 全 局 有 效 的 。ngx_http_stub_status_module 模 块 
将 负责 在 接收 到 相应 的 HTTP 查询 请 求 后 ， 把 这 些 统计 变量 以 HTTP 响应 的 方式 发 送 给 客户 
端 。 该 模块 也 可 以 作为 14.3 节 原子 变量 的 使 用 案例 。 
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14.3 ”原子 操作 


能 够 执行 原子 操作 的 原子 变量 只 有 整 型 ， 包 括 无 符号 整 型 ngx_ atomic uint t 和 有 符号 整 
型 ngx atomic t， 这 两 种 类 型 都 使 用 了 volatile 关 键 字 告诉 C 编 译 右 不 要 做 优化 。 





想 要 使 用 原子 操作 来 修改 、 获 取 整 型 变量 ， 自 然 不 能 使 用 加 减 写 ， 而 要 使 用 Nginx 提 供 
的 两 个 方法 : ngx atomic cmp set 和 ngx atomic fetch add。 这 两 个 方法 都 可 以 用 来 修改 原子 变 
量 的 值 ， 而 ngx atomic_ cmp _set 方 法 同时 还 可 以 比较 原子 变量 的 值 ， 下 面具 体 看 看 这 两 个 方 
法 5 








static ngx inline ngx _ atomic uint t ngx atomic cmp set (ngx _ atomic t *]lock, ngx atomic uint t old, ngx atomic uii 








ngx atomic cmp _ set 方法 会 将 old 参 数 与 原子 变量 lock 的 值 做 比较 ， 如 果 它 们 相等 ， 则 把 
lock 设 为 参数 set， 同 时 方法 返回 1;， 如 果 它 们 不 相等 ， 则 不 做 任何 修改 ， 返 回 0。 





static ngx inline ngx atomic int t ngx atomic fetch add(ngx atomic t *value, ngx atomic int t add) 








ngx atomic fetch add 方 法 会 把 原子 变量 value 的 值 加 上 参数 add， 同 时 返回 之 前 value 的 
值 。 


在 Nginx 各 种 锁 的 实现 中 ， 可 以 看 到 原子 变量 和 这 两 个 方法 的 多 种 用 法 。 


即使 操作 系统 的 内 核 无 法 提供 原子 性 的 操作 ， 那 么 Nginx 也 会 对 上 述 两 个 方法 提供 一 种 
实现 ， 这 在 14.3.1 节 中 会 简单 说 明 ; 对 于 各 种 硬件 体系 架构 ， 原 子 操作 的 实现 不 尽 相 同 ， 在 
14.3.2 节 中 将 会 以 最 常见 的 X86 架构 为 例 ， 说 明 Nginx 是 怎样 实现 上 述 两 个 原子 操作 方法 的 。 
在 14.3.3 节 ， 介 绍 Nginx 封 装 的 ngx spinlock 自 旋 锁 是 怎样 使 用 原子 变量 实现 的 。 
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14.3.1 不 支持 原子 库 下 的 原子 操作 





当 无 法 实现 原子 操作 时 ， 就 只 能 用 volatile 关 键 字 在 C 语 言 级 别 上 模拟 原子 操作 了。 事实 
上 ， 目 前 绝 大 多 数 体 系 架构 都 是 支持 原子 操作 的 ， 给 出 这 一 市 内 容 更 多 的 是 方便 读者 理解 
ngx atomic cmp_set 方 法 和 ngx atomic fetch add 方 法 的 意义 。 先 来 看 看 ngx atomic_cmp set 方 
法 的 实现 ， 如 下 所 示 。 








static ngx inline ngx atomic uint t ngx atomic cmp set (ngx atomic t *]lock, ngx atomic uint t old, ngx atomic uii 





// 当 原 子 变 量 


lock 与 


old 相 等 时 ， 才 能 把 


set 设 置 到 


lock 中 并 返回 


if (*lock == old) { 
*lock = set; 


Peturn. 1; 
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baad 
by 


// 若 原 子 变 


lock 与 


old 不 相等 ， 则 返回 


return 0; 





ngx_atomic fetch add 方 法 的 实现 也 很 简单 ， 如 下 所 示 。 





static ngx inline ngx atomic int t ngx atomic fetch add(ngx atomic t *value, ngx atomic int t add) { 





ngx atomic int t old; 


// 将 原子 变量 


value 加 上 


add 值 之 后 ， 再 返回 原先 


value 的 值 
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old = *value; 
*value += add; 


return old; 


14.3.2 ” x86 架构 下 的 原子 操作 





Nginx 要 在 源 代码 中 实现 对 整 型 的 原子 操作 ， 目 然 必须 通过 内 联 汇 编 语言 直接 操作 便 件 
才能 做 到 ， 本 节 以 基于 x86 的 SMP 多 核 架 构 为 例 来 看 看 Nginx 是 如 何 实现 这 两 个 基本 的 原子 操 
作 的 (由 于 参考 着 x86 架 构 下 的 实现 即 可 以 简 蛙 地 推导 出 其 他 架构 下 的 实现 ， 故 其 他 染 构 下 
的 原子 操作 实现 方法 不 再 一 一 说 明 ) 。 











使 用 GCC 编译 器 在 C 语 言 中 藤 入 汇编 语言 的 方式 是 使 用 _asm_ ”关键 字 ， 如 下 所 示 。 


asm volatile ( 汇编 语句 部 分 


: 输出 部 分 


: 输入 部 分 


XA 可 进 
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: 破坏 描述 部 分 





以 上 加 入 的 volatile 天 键 字 用 于 限制 GCC 编译 器 对 这 段 代 码 做 优化 。 


这 段 内 联 的 汇编 语言 包括 4 个 部 分 。 





(1) 汇编 语句 部 分 





引号 中 所 包含 的 汇编 语句 可 以 直接 用 占 位 符 % 来 引用 C 语 言 中 的 变量 (最 多 10 个 ， 
%0~%9) 。 





下 面 简单 介绍 一 下 随后 用 到 的 两 个 汇编 语句 ， 先 来 看 看 cmpxchglr,[m] 这 个 语句 ，Nginx 源 
代码 中 对 这 一 汇编 语句 有 一 段 伪 代码 注释 ， 如 下 所 示 。 





// 如 果 

eax 寄 存 器 中 的 值 等 于 
m 

if (eax == [m]) { 


// 将 
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zf 标志 位 设 为 


m 值 设 为 


// 如 果 


eax 寄 存 器 中 的 值 不 等 于 


m 
} else { 

// zf 标志 位 设 为 
0 


// 将 
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从 上 面 这 上段 伪 代 码 可 以 看 出 ，cmpxchgl r,[ml 语 句 首 先 会 用 m 比 较 eax 和 寄存 器 中 的 值 ， 如 果 
相等 ， 则 把 m 的 值 设 为 r， 同 时 将 zf 标志 位 设 为 1 ;否则 将 zf 标志 位 设 为 0。 


再 看 一 个 语句 sete[m|， 它 正好 配合 着 上 和 面 的 cmpxchgl 语 句 使 用 ， 这 里 不 妨 人 简单 地 认为 它 
的 作用 就 是 将 zf 标志 位 中 的 0 或 者 1 设置 到 m 中 。 





(2) 输出 部 分 

这 部 分 可 以 将 寄存 器 中 的 值 设置 到 C 语 言 的 变量 中 。 
(3) 输入 部 分 

可 以 将 C 语 言 中 的 变量 设置 到 寄存 器 中 。 

(4) 破坏 描述 部 分 

通知 编译 器 使 用 了 哪些 寄存 器 、 内 存 。 


简单 了 解 了 GCC 如 何 内 联 汇编 语言 后 ， 下 面 来 看 看 ngx_atomic_cmp _ set 方法 的 实现 ， 如 
下 所 示 。 


static ngx inline ngx _ atomic uint t ngx atomic cmp set (ngx atomic t *]lock, ngx atomic uint t old, ngx atomic uii 





{ 
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C 语 言 中 谋 入 汇编 语言 


asm volatile ( 


// 多 核 架构 下 首先 锁 住 总 线 


下 ERE2 


// 将 


*Tock 的 值 与 


eax 寄 存 器 中 的 


old 相 比较 ， 如 果 相 等 ， 则 置 
*]ock 的 值 为 


set 


"ompxehdgl %3, SL 
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zf 标志 位 


res 变 量 ， 否 则 


res 为 


: "=a" (res) : "m" (*]lock), "a" (old), "r" (set) : "cc", "memory") return res; 





现在 简单 地 说 明 一 下 上 述 代码 ， 在 嵌入 汇编 语言 的 输入 部 分 ，"m"(glocl9 表 示 间 ock 变 量 
是 在 内 存 中 ， 操 作 刀 ock 时 直接 通过 内 存 〈 不 使 用 寄存 器 ) 处 理 ， 而 "a"(old) 表 示 把 old 变 量 写 
入 eax 寄 存 器 中 ，'"Tr"(seb 表 示 把 set 变 量 写 入 通用 寄存 器 中 ， 这 些 都 是 在 为 cmpxchgl 语 句 做 准 
备 。“cmpxchgl1%3,%1” 相 当 于 “cmpxchglset*lock”( 含 义 参照 上 面 介 绍 过 的 伪 代 码 ) 。 这 3 行 汇 
编 语 句 的 意思 如 下 : 首先 锁 住 总 线 防 止 多 核 的 并 发 执行 ， 接 着 判断 原子 变量 *lock 与 old 值 是 
否 相 每 ， 夺 相等 ， 则 把 ock 值 设 为 set， 同 时 设 res 为 1， 方 法 返回 ; 硅 不 相等 ， 则 设 res 为 0， 
方法 返回 。 


在 了 解 ngx_atomic fetch add 方 法 前 ， 再 介绍 一 个 汇编 语句 xaddl。 下 面 先 来 看 看 Nginx 


及 未 EL 二 D: / / WN | i nuxprobe. con 





= temps 





可 以 看 到 ，xaddl 执 行 后 [ml] 值 将 为 r 和 [m] 之 和 ， 而 r 中 的 值 为 原 [m] 值 。 现 在 看 看 
ngx_atomic fetch add 方 法 是 如 何 实现 的 ， 如 下 所 示 。 





static ngx _ inline ngx atomic int t ngx atomic fetch add(ngx _ atomic t *value, ngx _ atomic int t addq) { 





asm volatile ( 


// 首先 锁 住 总 线 


TEGGkS" 


// *value 的 值 将 会 等 于 原先 


*vValue 值 与 


add 值 之 和 ， 而 


add 为 原 


*Value 值 


口 岂 日 所 有 由 和 所 有 由 http' /wNv inuxorobe. con 





"4 (addy 3 mv (value) 3 "coy, "memory")» 全 基站 997 





可 见 ，ngx atomic fetch add 将 使 得 *value 原 子 变量 的 值 加 上 add， 同 时 返回 原先 *value 的 
值 。 


14.3.3” 自 旋 锁 


基于 原子 操作 ，Nginx 实 现 了 一 个 目 旋 锁 。 目 旋 锁 是 一 种 非 睡 眠 锁 ， 也 就 是 说 ， 某 进程 
如 果 试 图 获得 目 旋 锁 ， 当 发 现 锁 已 经 被 其 他 进程 获得 时 ， 那 么 不 会 使 得 当前 进程 进入 睡眠 状 
态 ， 而 是 始终 保持 进程 在 可 执行 状态 ， 每 当 内 核 调 度 到 这 个 进程 执行 时 就 持续 检查 是 否 可 以 
获取 到 锁 。 在 拿 不 到 锁 时 ， 这 个 进程 的 代码 将 会 一 直 在 自 旋 锁 代码 处 执行 ， 直 到 其 他 进程 释 
放 了 锁 且 当前 进程 获取 到 了 锁 后 ， 代 码 才 会 继续 癌 下 执行 。 





可 见 ， 目 旋 锁 主要 是 为 多 处 理 器 操作 系统 而 设置 的 ， 它 要 解雇 的 共享 资源 保护 场景 就 是 
进程 使 用 锁 的 时 间 非 常 短 《〈“ 如 有 果 锁 的 使 用 时 间 很 入 ， 目 旋 锁 会 不 太 合 适 ， 那 么 它 会 占用 大 量 
的 CPU 资源 ) 。 在 14.6 节 和 14.7 市 介绍 的 两 种 睡 虐 锁 会 导致 进程 进入 睡眠 状态 。 睡 眠 锁 与 非 
睡眠 锁 应 用 的 场景 不 同 ， 如 果 使 用 锁 的 进程 不 太 和 希望 目 己 进入 睡眠 状态 ， 特 别 它 处 理 的 是 非 
常 核心 的 事件 时 ， 这 时 就 应 该 使 用 目 旋 锁 ， 其 实 大 部 分 情况 下 Nginx 的 worker 进 程 最 好 都 不 
要 进入 睡眠 状态 ， 因 为 它 非常 繁忙 ， 在 这 个 进程 的 epoll 上 可 能 会 有 十 万 甚至 百 万 的 TCP 连 接 
等 待 着 处 理 ， 进 程 一 旦 睡眠 后 必须 等 待 其 他 事件 的 唤醒 ， 这 中 间 极 其 频繁 的 进程 间 切 换 带 来 
的 负载 消耗 可 能 无 法 让 用 户 接受 。 




















@@ 注意 自 放 锁 对 于 单 处 理 器 操作 系统 来 说 一 样 是 有 效 的 ， 丰 进入 睡 眼 状态 并 不 意味 
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着 其 他 可 执行 状态 的 进程 得 不 到 执行 。Linux 内 核 中 对 于 每 个 处 理 器 都 有 一 个 运行 队列 ， 自 
旋 锁 可 以 仅仅 调整 当前 进程 在 运行 队列 中 的 顺序 ， 或 者 调整 进程 的 时 间 片 ， 这 都 会 为 当前 处 
理 器 上 的 其 他 进程 提供 被 调度 的 机 会 ， 以 使 得 锁 被 其 他 进程 释放 。 





用 户 可 以 从 锁 的 使 用 时 间 长 短 角度 来 选择 使 用 哪 一 种 锁 。 当 锁 的 使 用 时 间 很 短 时 ， 使 用 
目 旋 锁 非 常 合适 ， 尤 其 是 对 于 现在 普 损 存在 的 多 核 处 理 器 来 说 ， 这 样 的 开销 最 小 。 而 如 果 锁 
的 使 用 时 间 很 长 时 ， 那 么 一 旦 进程 拿 不 到 锁 就 不 应 该 再 执行 任何 操作 了 ， 这 时 应 该 使 用 睡眠 
锁 将 系统 资源 释放 给 其 他 进程 使 用 。 另 外 ， 如 果 进 程 拿 不 到 锁 ， 可 能 只 会 导致 某 一 类 请 求 
《不 是 进程 上 的 所 有 请 求 ) 不 能 继续 执行 ， 而 epoll 上 的 其 他 请 求 还 是 可 以 执行 的 ， 这 时 应 该 
选用 非 阻塞 的 互 斥 锁 ， 而 不 能 使 用 目 旋 锁 。 











下 面 介 绍 基于 原子 操作 的 自 旋 锁 方法 ngx_spinlock 是 如 何 实现 的 。 它 有 3 个 参数 ， 其 中 ， 
lock 参 数 就 是 原子 变量 表达 的 锁 ， 当 lock 值 为 0 时 表示 锁 是 被 释放 的 ， 而 lock 值 不 为 0 时 则 表示 
锁 已 经 被 某 个 进程 持 有 了 ;， value 参 数 表示 和 希望 当 锁 没有 被 任何 进程 持 有 时 《也 就 是 lock 值 为 
0) ， 把 lock 值 设 为 value 表 示 当 前 进程 持 有 了 锁 ;， 第 三 个 参数 spin 表 示 在 多 处 理 器 系统 内 ， 当 
ngx_spinlock 方 法 没有 拿 到 锁 时 ， 当 前 进程 在 内 核 的 一 次 调度 中 ， 该 方法 等 待 其 他 处 理 器 释 
放 锁 的 时 间 。 下 面 来 看 一 下 它 的 源 代码 。 











void ngx spinlock (ngx atomic 七 *lock, ngx atomic int t value, ngx uint t spin) { 
ngx uint 七 i, n; 


// 无 法 获取 锁 时 进程 的 代码 将 一 直 在 这 个 循环 中 执行 


for ( 7 ) { 


// lock 为 
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0 时 表示 锁 是 没有 被 其 他 进程 持 有 的 ， 这 时 将 


lock 值 设 为 


Value 参数 表示 当前 进程 持 有 了 锁 


if (*lock == 0 && ngx atomic cmp set(lock, 0, value)) I 


// 获取 到 锁 后 


ngx _spinlock 方 法 才 会 返回 


return; 


// ngx_ncpu 是 处 理 器 的 个 数 ， 当 它 大 于 


1 时 表示 处 于 多 处 理 器 系统 中 


if (ngx ncpu > 1) { 


/* 在 多 处 理 器 下 ， 更 好 的 做 法 是 当前 进程 不 要 立刻 “让 出 ”正在 使 用 的 


口 由 掉 岂 有 有 和 所 掉 由 http' /wNv inuxorobe. con 





CPU 处 理 器 ， 而 是 等 待 一 段 时 间 ， 看 看 其 他 处 理 器 上 的 进程 是 否 会 释放 锁 ， 这 会 减少 进程 间 切 换 的 次 数 


*/ 
for (n= 1; n < spin; n <<= 1) { 

/x* 注 意 ， 随 着 等 待 的 次 数 越 来 越 多 ， 实 际 去 检查 
lock 是 否 释 放 的 频繁 会 越 来 越 小 。 为 什么 会 这 样 呢 ? 因 为 检查 
lock 值 更 消耗 
CPU， 而 执行 
ngx_ cpu pause 对 于 
CPU 的 能 耗 来 说 是 很 省 电 的 

yy 


for (i = 0; i < ny i++) { 


/*ngx_cpu_pause 是 在 许多 架构 体系 中 专门 为 了 自 旋 锁 而 提供 的 指令 ， 它 会 告诉 


CPU 现在 处 于 自 旋 锁 等 待 状态 ， 通 常 一 些 


CPU 会 将 自己 置 于 节能 状态 ， 降 低 功 耗 。 注 意 ， 在 执行 
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ngx_cpu _ pause 后， 当前 进程 没有 “让 出 ” 正 使 用 的 处 理 器 


人 
ngx cpu pause(); 1} 
/* 检 查 锁 是 否 被 释放 了 ， 如 果 
lock 值 为 
0 且 释 放 了 锁 后 ， 就 把 它 的 值 设 为 
value， 当 前 进程 持 有 锁 成 功 并 返回 
sf 
if (*]lock == 0 && ngx atomic cmp set (lock, 0, value)) { 


return; 


/* 当 前 进程 仍然 处 于 可 执行 状态 ,但 暂时 “让 出 ”处 理 器 ， 使 得 处 理 器 优先 调度 其 他 可 执行 状态 的 进程 ， 这 样 ， 在 进程 被 内 核 再 次 调度 时 ， 


for 循 环 代码 中 可 以 期 望 其 他 进程 释放 锁 。 注 意 ， 不同 的 内 核 版 本 对 于 
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sched yield 系统 调用 的 实现 可 能 是 不 同 的 ， 但 它们 的 目的 都 是 暂时 “让 出 ”处 理 器 


ngx sched yieldq() 





释放 锁 时 需要 Nginx 模 块 通过 ngx atomic cmp _set 方 法 将 原子 变量 lock 值 设 为 0。 





可 以 看 到 ，ngx_spinlock 方 法 是 非常 高 效 的 目 旋 锁 ， 它 充分 考虑 了 单 处 理 器 和 多 处 理 器 
的 系统 ， 对 于 持 有 锁 时 间 非 常 短 的 场景 很 有 效率 。 
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14.4 Nginx 频 道 


ngx_channel 堪 道 是 Nginx master 进 程 与 worker 进 程 之 间 通 信 的 常用 工具 ， 它 是 使 用 本 机 
套 接 字 实现 的 。 下 面 先 来 看 看 socketpair 方 法 ， 它 用 于 创建 父子 进程 间 使 用 的 套 接 字 。 


int Socketpair(int d, int type int protocol, int sv[2]); 


这 个 方法 可 以 创建 一 对 关联 的 套 接 字 sv[2]。 下 面 依次 介绍 它 的 4 个 参数 : 参数 d 表 示 域 ， 
在 Linux 下 通常 取 值 为 AF UNIX; type 取 值 为 SOCK _ STREAM 或 者 SOCK DGRAM， 它 表示 在 
套 接 字 上 使 用 的 是 TCP 还 是 UDP; protocol 必 须 传递 0，sv[2] 是 一 个 含有 两 个 元 素 的 整 型 数 
组 ， 实 际 上 就 是 两 个 套 接 字 。 当 socketpair 返 回 0 时 ，sv[2] 这 两 个 套 接 字 创 建成 功 ， 否 则 
socketpair 返 回 -1 表 示 失 败 。 








当 socketpair 执 行 成 功 时 ，sv[2] 这 两 个 套 接 字 具备 下 列 关 系 : 问 sv[0] 套 接 字 写 入 数据 ， 
将 可 以 从 sv[1] 套 接 字 中 读 取 到 刚 写 入 的 数据 ;同样 ， 同 sy[]] 套 接 字 写 入 数据 ， 也 可 以 从 
sv[0] 中 读 取 到 写 入 的 数据 。 通 常 ， 在 父 、 子 进程 通信 前 ， 会 先 调 用 socketpair 方 法 创建 这 样 
一 组 套 接 字 ， 在 调用 fork 方 法 创建 出 子 进 程 后 ， 将 会 在 父 进 程 中 关 财 sv[]] 套 接 字 ， 仅 使 用 
sv[0] 套 接 字 用 于 辣子 进程 发 送 数据 以 及 接收 子 进程 发 送 来 的 数据 ;而 在 子 进程 中 则 关闭 
sv[0] 套 接 字 ， 仅 使 用 sv[1] 套 接 字 既 可 以 接收 父 进程 发 来 的 数据 ， 也 可 以 问 父 进程 发 送 数 
据 。 





再 来 介绍 一 下 ngx_channel t 频 道 。ngx_channel tt 结构 体 是 Nginx 定 义 的 master 父 进程 与 
worker 子 进程 间 的 消息 格式 ， 如 下 上 所 示 。 


typedef struct { 


// 传递 的 
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TCP 消 息 中 的 命令 


ngx uint t command; 


// 进程 


ID， 一 般 是 发 送 


依 
坟 


方 的 进程 


各 


ID 


ngx pid t pid; 


// 表示 发 送 命 令 方 在 


ngx processes 进 程 数组 间 的 序号 


ngx_ int 七 slot; 


// 通信 的 套 接 字 和 句柄 


ngx fd 七 fd; 


} ngx channel t; 


这 个 消 妃 的 格式 似乎 过 


于 简单 了 ， 


没 错 ， 


因为 Nginx 仅 用 这 个 频道 





同步 master 进 程 与 
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worker 进 程 则 的 状态 ， 这 点 从 针对 command 成 员 已 经 定义 的 命令 束 可 以 看 出 来 ， 如 下 所 示 。 





// 打开 频道 ， 使 用 频道 这 种 方式 通信 前 必须 发 送 的 命令 


#define NGX CMD OPEN CHANNEL 1 








// 关闭 已 经 打开 的 频道 ， 实 际 上 也 就 是 关闭 套 接 字 














#define NGX CMD CLOSE CHANNEL 2 


// 要 求 接收 方正 常 地 退出 进程 


#define NGX CMD QUIT 3 


// 要 求 接收 方 强制 地 结束 进程 





#define NGX CMD TERMINRATE 4 














// 要 求 接收 方 重新 打开 进程 已 经 打开 过 的 文件 





#define NGX CMD REOPEN 5 














在 8.6 节 我 们 介绍 过 master 进 程 是 如 何 监控 、 管 理 worker 子 进程 的 ， 那 图 8-8 中 的 master 又 
是 如 何 启 动 、 停 止 worker 子 进程 的 呢 ? 正 是 通过 socketpair 产 生 的 套 接 字 发 送 命令 的 ， 即 每 次 
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要 派生 一 个 子 进程 之 


A 


前 


， 都 会 先 调 用 socketpair 方 法 。 在 Nginx 派 生子 进程 的 


ngx_spawn process 方 法 中 ， 会 首先 派生 基于 TCP 的 套 接 字 ， 如 下 所 示 。 





ngx pid t ngx spawn process(ngx cycle t cycle, ngx spawn proc pt Proc void data, char xname ngx int t respawn, 





// ngx processes[s] .channel 数 组 正 是 将 要 用 于 父 、 子 进程 间 通 信 的 套 接 字 对 


if (socketpair (AF UNIX, SOCK STR 


return NGX INVALID PID; 


// 接 下 来 会 把 


channe1 套 接 字 对 都 设置 为 非 阻塞 模式 





EAM, 0, ngx processes [s] .channel) == -1) { 





上 上 段 代 码 提 到 的 ngx processes 数 组 定义 了 Nginx 服 务 中 所 有 的 进程 ， 包 括 master 进 程 和 
worker 进 程 ， 如 下 所 示 。 





#define NGX MAX PROCE 








SS 





ES 1024 
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// 虽然 定义 了 





NGX_MAX PROCESSES 个 成 员 ,， 但 已 经 使 用 的 元 素 仅 与 启动 的 进程 个 数 有 关 




















ngx process t ngx processes[NGX MAX PROCESSES]; 








它 的 类 型 是 ngx process t， 对 于 频道 来 说 ， 这 个 结构 体 只 关心 它 的 channel 成 员 。 





typedef struct { 


// socketpair 创 建 的 套 接 字 对 


ngx socket t channel[2]; 


} ngx process 七; 











如 何 使 用 频道 发 送 ngx channel t 消 息 呢 ? Nginx 封 装 了 4 个 方法 ， 首 先 来 看 看 用 于 发 送 消 
县 的 ngx write_channel 方 法。 





ngx int t ngx write _ channel (ngx _ Socket t s, ngx channel t *ch, size t size, ngx log 七 x*1og) ; 








这 里 的 s 参 数 是 要 使 用 的 TCP 套 接 字 ，ch 参 数 是 ngx_channel t 类 型 的 消息 ，size 人 参数 是 
ngx_channel tt 结构 体 的 大 小 ，log 参 数 是 日 志 对 象 。 
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再 来 看 看 读 取消 息 的 方法 ngx read_channel。 





ngx _ int t ngx read channel (ngx socket t s, ngx channel t *ch, size t size, ngx log 七 x*1og) ， 

















这 里 的 参数 意义 与 ngx_write_channel 方 法 完全 相同 ， 只 是 要 注意 s 套 接 字 ， 它 与 发 送 方 使 
用 的 s 套 接 字 是 配对 的 。 例 如 ， 在 Nginx 中 ， 目 前 仅 存 在 master 进 程 向 worker 进 程 发 送 消息 的 
场景 ， 这 时 对 于 socketpair 方 法 创建 的 channel[2] 套 接 字 对 来 说 ，master 进 程 会 使 用 channel[0] 套 
接 字 来 发 送 消息 ， 而 worker 进 程 则 会 使 用 channel[1] 套 接 字 来 接收 消息 。 








worker 进 程 是 怎样 调度 ngx_ read_channel 方 法 接收 频道 消息 昵 ? 毕竟 Nginx 是 单线 程 程 
序 ， 这 唯一 的 线程 还 ee 
方法 把 接收 频道 消息 的 套 接 字 添加 到 epoll 中 了 ， 当 接收 到 父 进程 消息 时 子 进程 会 通过 epoll 的 
事件 回调 相应 的 handler 方 法 来 处 理 这 个 频道 消息 ， 如 下 所 示 。 











ngx int t ngx add channel event (ngx cycle t *cycle, ngx fd t fd, ngx int t event, ngx event handler pt handler) 








cycle 参 数 自然 是 每 个 Nginx 进 程 必须 具备 的 ngx_cycle tt 核心 结 构 体 ，fd 参 数 就 是 上 面 说 过 





的 需要 接收 消 明 的 套 接 字 ， 对 于 worker 子 进程 来 说 ， 就 是 对 应 的 channel[1] 套 接 字 ; event 参 数 
是 需要 检测 的 事件 类 型 ， 在 上 述 场 景 下 必然 是 EPOLLIN; handler 参 数 指向 的 方法 就 是 用 于 读 


取 频 道 消息 的 方法 ，Nginx 定 义 了 一 个 ngx_channel handler 方 法 用 于 处 理 频道 消息 。 


当 进 程 希望 关闭 这 个 频道 通信 方式 时 ， 可 以 调用 ngx_close_channel 方 法 ， 它 会 关闭 这 对 
套 接 字 ， 如 下 所 示 。 





void ngx close channel (ngx fd t fd, ngx 1og t 109g); 





参数 向 就 是 上 面 说 过 的 channel[2] 套 接 字 数组 。 
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14.5 昼 号 


Linux 提 供 了 以 信号 传递 进程 间 消 息 的 机 制 ，Nginx 在 管理 master 进 程 和 worker 进 程 时 大 量 
使 用 了 信和 号。 什么 是 信号 ? 它 是 一 种 非常 短 的 消息 ， 短 到 只 有 一 个 数字 。 在 中 文 译 名 中 ， 信 
号 相 比 下 文 将 要 介绍 的 信号 量 只 少 了 一 个 字 ， 但 它们 完全 是 两 个 概念 ， 信 和 号 量 仅 用 于 同步 代 
码 段 ， 而 信号 则 用 于 传递 消息 。 一 个 进程 可 以 回 另 外 一 个 进程 或 者 另外 一 组 进程 发 送信 号 消 

通知 目标 进程 执行 特定 的 代码 。 














Linux 定 义 的 前 31 个 信号 是 最 第 用 的 ，Nginx 则 通过 重 定 义 其 中 一 些 信号 的 处 理 方法 来 使 
用 信号 ， 如 接收 到 SIGUSR1 信 和 号 就 意味 着 需要 重新 打开 文件 。 使 用 信号 时 Nginx 定 义 了 一 个 
ngx_signal_{t 结 构 体 用 于 描述 接收 到 信号 时 的 行为 ， 如 下 所 示 。 











typedef struct { 


// 需要 处 理 的 信号 


int ‘Sionos 


// 信号 对 应 的 字符 串 名 称 


char *signame; 


// 这 个 信号 对 应 着 的 


Nginx 命 令 
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char *name; 


// 收 到 


signo 信 号 后 就 会 回调 


handler 方 法 


void (*handler) (int signo); 


} ngx Signal t; 





另外 ，Nginx 还 定义 了 一 个 数组 ， 用 来 定义 进程 将 会 处 理 的 所 有 信号。 例如 ; 





#define NGX RECONFIGURE SIGNAL HUP 








ngx signal t signals[] = { 


{ ngx signal value (NGX RECONFIGURE SIGNAL), "SIG" ngx Value (NGX RECONFIGURE SIGNAL), "reload", 














ngx signal handler }, 











上 面 的 例子 意味 着 在 接收 到 SIGHUP 信 号 后 ， 将 调用 ngx_signal_handler 方 法 进行 处 理 ， 以 


便 重 新 读 取 配置 文件 ， 或 者 说 ， 当 收 到 用 户 es 
TT D: // WAW i i nuxorobe. con 








./nginx -s reload 





这 个 新 局 动 的 Nginx 进 程 会 问 实 际 运行 的 Nginx 服 务 进程 发 送 SIGHUP 信 号 〈 执 行 这 个 命令 后 拉 
起 的 Nginx 进 程 并 不 会 重新 启动 服务 器 ， 而 是 仅 用 于 发 送信 号 ， 在 ngx_get_ options 方 法 中 会 重 
AN 而 main 方 法 中 检查 到 其 非 0 时 就 会 调用 ngx_signal a 

运行 的 Nginx 服 务 发 送信 号 ， 之 后 main 方 法 就 会 返回 ， 新 局 动 的 Nginx 进 程 退出 ) ， 这 样 运 
中 的 服务 进程 也 会 调用 ngx _ signal handler 方 法 来 处 理 这 个 信号 


在 定义 了 ngx_signal t 类 型 的 signals 数 组 后 ，ngx init signals 方 法 会 初始 化 所 有 的 信号 ， 如 
下 所 示 。 





ngx _ int t ngx init signals (ngx log t *]log) { 





ngx signal 七 *sig; 


// Linux 内 核 使 用 的 信号 


struct sigaction sa; 


signals 数 组 ， 处 理 每 一 个 


ngx_ signal 七 类 型 的 结构 体 


= signals; sig->signo |!= 


下 下 站 痛 站 下 站 让 有 httpD' / /waw | i nuxprobe. con 





ngx memzero (&sa， Sizeof (Struct sigaction)); // 设置 信号 的 处 理 方法 为 


handler 方 法 


sa.sa handler = sig->handler; // 将 


sa 中 的 位 全 部 置 为 


sigemptyset (&sa.sa mask); // 向 


Linux 注 册 信 号 的 回调 方法 


if (sigaction(sig->signo, &sa, NULL) == -1) { 














ngx log error (NGX LOG EMERG, log, ngx errno, "sigaction(%s) failed", sig->signame); return NGX ERROI! 





return NGX OK; 





训 村 洁 和 下 外 名 从 忆 二 加 内 用 户 光 sip 信人 





signals 数 组 中 添加 新 的 ngx_signal tt 成 员 。 
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14.6 ”信号 量 





诗 写 量 与 信号 个 同 ， 它 不 像 信 己 那样 用 来 传递 消 恩 ， 而 是 用 来 保证 两 个 或 多 个 代码 段 不 
被 并 有 访问， 是 一 种 保证 共享 资源 有 序 访问 的 工具 。 使 用 信号 量 作为 互 斥 锁 有 可 能 导致 进程 
睡眠 ， 因 此 ， 要 谨慎 使 用 ， 特 别 是 对 于 Nginx 这 种 每 一 个 进程 同时 人 处理 着 数 以 万 计 请 求 的 服 
务 需 来 说 ， 这 种 导致 睡眠 的 操作 将 有 可 能 造成 性 能 大 幅 降低 。 











信号 量 提供 的 用 法 非常 多 ， 但 Nginx 仅 把 它 作 为 简单 的 互 斥 锁 来 使 用 ， 下 面 只 会 介绍 这 
种 用 法 。 定 义 一 个 sem t 类 型 的 变量 后 ， 即 可 围绕 着 它 使 用 信号 量 。 使 用 前 ， 先 要 调用 
sem init 方 法 初始 化 信号 量 ， 如 下 所 示 。 


int sem init(sem t *sem, int pshared, unsigned int value); 








其 中 ， 参 数 sem 即 为 我 们 定义 的 信号 量 ， 而 参数 pshared 将 指明 sem 信 号 量 是 用 于 进程 间 
同步 还 是 用 于 线程 间 同 步 ， 当 pshared 为 0 时 表示 线程 间 同 步 ， 而 pshared 为 1 时 表示 进程 间 同 

。 由 于 Nginx 的 每 个 进程 都 是 单线 程 的 ， 因 此 将 参数 pshared 设 为 1 即 可 。 人 参数 value 表 示 信 和 号 
量 sem 的 初始 值 。 下 面 看 看 在 ngx shmtx _ create 方法 中 是 如 何 初始 化 信号 量 的 。 











ngx _ int t ngx shmtx create(ngx shmtx 七 xmtXx void addr, u char name) { 








#if (NGX HAVE POSIX SEM 





// 信号 量 


mtx->sem 初 始 化 为 
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0， 用 于 进程 间 通 信 


if (sem init(&mtx->sem，1，0) == -1) { 





ngx log _ error (NGX LOG ALERT, ngx cycle->log, ngx errno, "sem init() failed"); } else { 


mtx->semaphore = 1; 


#endif 


return NGX OK; 





ngx_shmtx_t 结 构 体 将 会 在 14.8 闻 中 介绍 。 可 以 看 到 ， 在 定义 了 NGX_HAVE POSIX_SEM 
宏 后 ， 将 开始 使 用 信号 量 。 另 外 ，sem destroy 方 法 可 以 销毁 信号 量 。 例 如 : 





void ngx shmtx destory(ngx shmtx 七 *mtx) { 





#if (NGX HAVE POSIX SEM) 





if (mtx->semaphore) { 


if (sem destroy(&mtx->sem) == -1) { 





ngx log error (NGX LOG ALERT, ngx cycle->log, ngx errno, "sem destroy() failed"); } 


#endif 
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信号 量 是 如 何 实现 互 斥 锁 功 能 的 呢 ? 例如 ， 最 初 的 信号 量 sem 值 为 0， 调 用 sem post 方 法 
将 会 把 sem 值 加 1， 这 个 操作 不 会 有 任何 阻塞 ， 调 用 sem_wait 方 法 将 会 把 信号 量 sem 的 值 减 1， 
如 果 sem 值 已 经 小 于 或 等 于 0 了 ， 则 阻塞 住 当前 进程 〈 进 程 会 进入 睡眠 状态 ) ， 直 到 其 他 进程 
将 信号 量 sem 的 值 改 变 为 正 数 后 ， 这 时 才能 继续 通过 将 sem 减 1 而 使 得 当前 进程 继续 向 下 执 
行 。 因 此 ，sem post 方 法 可 以 实现 解锁 的 功能 ， 而 sem_wait 方 法 可 以 实现 加 锁 的 功能 。 





例如 ，ngx shmtx lock 方 法 在 加 锁 时 ， 有 可 能 到 使 用 sem_ wait 的 分 支 去 试图 获得 锁 ， 如 下 
所 示 。 





void ngx shmtx lock(ngx shmtx 七 *mtx) { 


// 如 果 没 有 拿 到 锁 ， 这 时 


Nginx 进 程 将 会 睡眠 ， 直 到 其 他 进程 释放 了 锁 


while (sem wait (&mtx->sem) == -1) { 








ngx_Shmtx lock 方 法 会 在 14.8 节 详细 说 明 。ngx _shmtx unlock 方 法 在 释放 锁 时 也 会 用 到 
sem post 方 法 ， 如 下 所 示 。 





void ngx shmtx unlock(ngx shmtx 七 *mtx) { 


// 释放 信号 量 锁 时 是 不 会 使 进程 睡眠 的 


if (sem post(&mtx->sem) == -1) { 





ngx log _ error (NGX LOG ALERT, ngx cycle->log, ngx errno, "sem post() failed while wake shmtx"); } 








在 14.8 市 中 我 们 将 会 讨论 Nginx 古 如 何 让 原子 变量 和 信号 量 合作 以 实现 高 效 互 斥 锁 的 。 
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14.7 ”文件 锁 


Linux 内 核 提 供 了 基于 文件 的 互 斥 锁 ， 而 Nginx 框 架 封 装 了 3 个 方法 ， 提 供给 Nginx 模 块 使 
用 文件 互 斥 锁 来 保护 共 孚 数据 。 下 面 首 先 介绍 一 下 这 种 基于 文件 的 互 斥 锁 是 如 何 使 用 的 ， 其 
实 很 简单 ， 通 过 fcnt 方 法 就 可 以 实现 。 








int .fentl (int fad; int. cmd;, struct flock *lock); 


这 个 方法 接收 3 个 参数 ， 其 中 参数 但是 打开 的 文件 句柄 ， 参 数 cmd 表 示 执 行 的 锁 操 作 ， 参 
数 lock 描 述 了 这 个 锁 的 信息 。 下 面 依次 说 明 这 3 个 参数 。 


参数 f 色 必须 是 已 经 成 功 打开 的 文件 句柄 。 实 际 上 ，nginx.conf 文 件 中 的 lock _ file 配置 项 指 
定 的 文件 路 径 ， 就 是 用 于 文件 互 斥 锁 的 ， 这 个 文件 被 打开 后 得 到 的 句柄 ， 将 会 作为 得 参数 传 
递 给 fcnt 方 法 ， 提 供 一 种 锁 机 制 。 





这 里 的 cmd 参 数 在 Nginx 中 只 会 有 两 个 值 : F SETLK 和 F SETLKW， 它 们 都 表示 试图 获得 
互 斥 锁 ， 但 使 用 F_ SETLK 时 如 果 互 斥 锁 已 经 被 其 他 进程 占用 ，fent 方 法 不 会 等 待 其 他 进程 释 
放 锁 且 自 己 拿 到 锁 后 才 返 回 ， 而 是 立即 返回 获取 互 斥 锁 失 败 ; 使 用 F_SETLKW 时 则 不 同 ， 锁 
被 占用 后 fentl 方 法 会 一 直 等 待 ， 在 其 他 进程 没有 释放 锁 时 ， 当 前 进程 就 会 阻 窟 在 fentl 方 法 
中 ， 这 种 阻塞 会 导致 当前 进程 由 可 执行 状态 转 为 睡眠 状态 。 





参数 lock 的 类 型 是 flock 结 构 体 ， 它 有 5 个 成 员 是 需要 用 户 关 心 的 ， 如 下 所 示 。 


StEuet ELOGkK i 
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F_RDLCK.、 


F_WRLCK 或 


F_UNLCK 
short 1 type; 


// 锁 区 域 起 始 地 址 的 相对 位 置 


short 1 whence; 


// 锁 区 域 起 始 地 址 偏 移 量 ， 同 


1_whence 共 同 确定 锁 区 域 


Iong 1 start; 


// 锁 的 长 度 ， 


0 表示 锁 至 文件 末 


long 1 len; 
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// 拥有 锁 的 进程 


Long 1 Bid; 








从 flock 结 构 体 中 可 以 看 出 ， 文 件 锁 的 功能 绝 不 仅仅 局 限于 普通 的 互 斥 锁 ， 它 还 可 以 锁 住 
文件 中 的 部 分 内 容 。 但 Nginx 封 装 的 文件 锁 仅 用 于 保护 代码 段 的 顺序 执行 〈 例 如， 在 进行 负 
载 均 衡 时 ， 使 用 互 斥 锁 保 证 同一 时 刻 仅 有 一 个 worker 进 程 可 以 处 理 新 的 TCP 连 接 ) ， 使 用 方 
式 要 简单 得 多 : 一 个 lock file 文 件 对 应 一 个 全 局 互 斥 锁 ， 而 且 它 对 master 进 程 或 者 worker 进 程 
都 生效 。 因 此 ， 对 于 1_start、1 len、1 pid， 都 填 为 0%， 而 1 _whence 则 填 为 SEEK_SET， 只 需要 
这 个 文件 提供 一 个 锁 。1 type 的 值 则 取决 于 用 户 是 想 实 现 阻 塞 睡眠 锁 还 是 想 实 现 非 阻塞 不 会 
睡眠 的 锁 。 


对 于 文件 锁 ，Nginx 封 装 了 3 个 方法 : ngx trylock 和 实现 了 不 会 阻塞 进程 、 不 会 使 得 进程 
进入 睡眠 状态 的 互 斥 锁 ; ngx_lock 季 提 供 的 互 斥 锁 在 锁 已 经 被 其 他 进程 拿 到 时 将 会 导致 当前 
进程 进入 睡眠 状态 ， 直 到 顺利 拿 到 这 个 锁 后 ， 当 前 进程 才 会 被 Linux 内 核 重新 调度 ， 所 以 它 
是 阻塞 操作 ;ngx_unlock 人 锯 用 于 释放 互 斥 锁 。 下 面 我 们 一 一 列举 它们 的 源 代码 。 





ngx err t ngx trylock fd(ngx fd 七 fdq) { 
Stuct ELocGk ££L; 


// 这 个 文件 锁 并 不 用 于 锁 文 件 中 的 内 容 ， 填 充 为 


fis. tart s 02 
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fl ul ER 二 07 


f1.1 pid = 0; 





// F_SETLK 意 味 着 不 会 导致 进程 睡眠 


fl1.1 type = F WRLCK; 

















fl1.1 whence = SEEK SET; // 获取 


fd 对 应 的 互 斥 锁 ， 如 果 返 回 


-1， 则 这 时 的 


ngx_errno 将 保存 错误 码 


if (fentl (fd;y EF SETLKR;: &f1) == =1) 





return ngx errno; } 


return 0; 








使 用 ngx_trylock 人 方法 获取 互 斥 锁 成 功 时 会 返回 0， 人 否则 返回 的 其 实 是 errno 错 误 码 ， 而 
这 个 错误 码 为 NGX EAGAIN 或 者 NGX EACCESS 时 表示 当前 没有 拿 到 互 斥 锁 ， 否 则 可 以 认 
为 fcnt 执 行 错 误 。 
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ngx_lock 人 方法 将 会 阻塞 进程 的 执行 ， 使 用 时 需要 非常 谨慎 ， 它 可 能 会 导致 worker 进 程 
宁可 睡眠 也 不 处 理 其 他 正常 请 求 ， 如 下 所 示 。 





x err t ngx lock fd(ngx fd t fd) { 





struct flock fl; 


fl start s 0» 


ELL Len' S03 


Fil, pid = 0; 





// F_SETLKW 会 导致 进程 睡眠 


fl1.1] type = F WRLCK; 





f1.1 whence = SEEK SET; // 如 果 返 回 














-1， 则 表示 


fcnt1 执 行 错 误 。 一 旦 返回 


0， 表 示 成 功 地 拿 到 了 锁 


if (fentl(fd; F .SETLKW, &f1) == =1) { 





return ngx errnor 
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return 0; 





只 要 ngx lock 和 9 方法 返回 0， 就 表示 成 功 地 拿 到 了 互 斥 锁 ， 否 则 就 是 加 锁 操 作出 现 错 


ngx_unlock 全 方法 用 于 释放 当前 进程 已 经 拿 到 的 互 斥 锁 ， 如 下 所 示 。 





ngx err t ngx unlock fd(ngx fd 七 fd) { 





struct flock fil; 


fl Start = 02 


fl sl en S03 








f1l.1 pid = 0; 


// F_UNLCK 表 示 将 要 释放 和 锁 


flL.1 type = F UNLCK; 





fl.1 whence = SEEK SET; // 返回 














0 表示 成 功 


if (fentl(fd; EF SETLK; &f1) == =1) 并 
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return 0; 


当 关 闭 锯 句柄 对 应 的 文件 时 ， 当 前 进程 将 自动 释放 已 经 拿 到 的 锁 。 
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14.8 互 斥 锁 


基于 原子 操作 、 信 号 量 以 及 文件 锁 ，Nginx 在 更 高 层次 封装 了 一 个 互 斥 锁 ， 使 用 起 来 很 
方便 ， 许 多 Nginx 模 块 也 是 更 多 直接 使 用 它 。 下 面 看 一 下 表 14-1 中 介绍 的 操作 这 个 互 斥 锁 的 5$ 
种 方法 。 


表 14-1 互 斥 锁 的 5 种 操作 方法 


方法 名 参 数 
参数 mtx 表示 待 操作 的 ngx_shmtx t 类 型 互 斥 锁 ; 
当 互 斥 锁 由 原子 变量 实现 时 ， 参 数 addr 表示 要 操作 
ngx shmtx _ create 的 原子 变量 锁 ， 而 互 斥 锁 由 文件 实现 时 ， 参 数 addr| 初始 化 mtx 互 斥 锁 
没有 任何 意义 ; 参数 name 仅 当 互 斥 锁 由 文件 实现 时 
才 有 意义 ， 它 表示 这 个 文件 所 在 的 路 径 及 文件 名 


让 
/© 


ngx shmtx destory 参数 mtx 表示 待 操作 的 ngx_shmtx t 类 型 互 斥 锁 销毁 mtx 互 斥 锁 
无 阻塞 地 试图 获取 互 斥 锁 ， 返 回 
ngx shmtx trylock 参数 mtx 表示 待 操作 的 ngx_shmtx t 类 型 互 斥 锁 ”11 表示 获取 互 斥 锁 成 功 ， 返 回 0 表 


示 获 取 互 斥 锁 失 败 
以 阻塞 进程 的 方式 获取 互 斥 锁 ， 
在 方法 返回 时 就 已 经 持 有 互 斥 锁 了 


ngx shmtx unlock 参数 mtx 表示 待 操作 的 ngx_shmtx t 类 型 互 斥 锁 释放 互 斥 锁 


ngx shmtx lock 参数 mtx 表示 待 操作 的 ngx_shmtx t 类 型 互 斥 锁 





表 14-1 中 的 $ 种 方法 非 党 全面， 获取 互 斥 锁 时 既 可 以 使 用 不 会 阻 赛 进 程 的 
ngx_shmtx_ trylock 方 法 ， 也 可 以 使 用 ngx_shmtx_ lock 方法 告诉 Nginx 必 须 持 有 互 斥 锁 后 才能 继续 
问 下 执行 代码 。 它 们 都 通过 操作 ngx_shmtx t 关 型 的 结构 体 来 实现 互 斥 操作 ， 下 面 再 来 看 一 下 
ngx_shmtx_t 中 有 哪些 成 员 ， 如 下 所 示 。 











typedef struct { 


#if (NGX HAVE ATOMIC OPS) 





// 原子 变量 锁 
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ngx atomijc t *lock; 


#if (NGX HAVE POSIX SEM) 








// semaphore 为 


1 时 表示 获取 锁 将 可 能 使 用 到 的 信号 量 


ngx uint t semaphore; 


// sem 就 是 信号 量 锁 


Sem 七 sem; 
#endif 
#else 


// 使 用 文件 锁 时 


fd 表示 使 用 的 文件 句柄 


ngx fd 七 fd; 


// name 表 示 文 件 名 
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u char *name; 


#endif 


/* 自 旋 次 数 ， 表 示 在 自 旋 状 态 下 等 待 其 他 处 理 器 执行 结果 中 释放 锁 的 时 间 。 由 文件 锁 实 现时 ， 


spin 没 有 任何 意义 


2 


ngx uint t spin; 


} ngx shmtx t; 





@ i 读者 可 能 会 觉得 奇怪 ， 既 然 ngx_shmtx_t 结 构 体 中 的 spin 成 员 对 于 文件 锁 没 有 
任何 意义 ， 为 什么 不 放 在 析 f(NGX_HAVE_ATOMIC_OPS) 宏 内 呢 ? 这 是 因为 ， 对 于 使 用 
ngx_shmtx_t 互 斥 锁 的 代码 来 说 ， 它 们 并 不 想 知道 互 斥 锁 是 由 文件 锁 、 原 子 变 量 或 者 信号 量 实 
现 的 。 同 时 ，spin 的 值 又 具备 非常 多 的 含义 〈C 语 言 的 编程 风格 导致 可 读 性 比 面向 对 象 语言 
差 些 ) ， 当 仅 用 原子 变量 实现 互 斥 锁 时 ，spin 只 表示 自 旋 等 待 其 他 处 理 器 的 时 间 ， 达 到 spin 
值 后 就 会 ”让 出 ”当前 处 理 器 。 如 果 spin 为 0 或 者 负 值 ， 则 不 会 存在 调用 PAUSE 的 机 会 ， 而 是 
直接 调用 sched_yield“ 让 出 ”处 理 器 。 假 设 同 时 使 用 信号 量 ，spin 会 多 一 种 含义 ， 即 当 spin 值 
为 (ngx_uint_bD -1 时 ， 相 当 于 告诉 这 个 互 斥 锁 绝 不 要 使 用 信号 量 使 得 进程 进入 睡眠 状态 。 这 


点 很 重要 ， 实 际 上 ， 在 实现 第 9 章 提 到 的 负载 均衡 锁 时 ，spin 的 值 就 是 ngx_uint D - 1。 


可 以 看 到 ，ngx_shmtx t 结 构 体 涉及 两 个 宏 : NGX_HAVE_ATOMIC_OPS、 
NGX_HAVE_POSIX_SEM， 这 两 个 宏 对 应 着 互 斥 锁 的 3 种 不 同 实现 。 


第 1 种 实现 ， 当 不 文 持 原子 操作 时 ， 会 使 用 文件 锁 来 实现 ngx_shmtx t 互 斥 锁 ， 这 时 它 仅 
有 生 和 name 成 员 〔( 实 际 上 还 有 spin 成 员 ， 但 这 时 没有 任何 意义 〉)。 这 两 个 成 员 使 用 14.7 节 介 


ee 





第 2 种 实现 ， 文 持原 子 操作 却 又 不 文 持 信号 量 。 
第 3 种 实现 ， 在 文 持 原子 操作 的 同时 ， 操 作 系 统 也 文 持 信和 号 量 。 


后 两 种 实现 的 唯一 区 别 是 ngx_shmtx_lock 方 法 执行 时 的 效果 ， 也 就 是 说 ， 文 持 信 号 量 只 
会 影响 阻塞 进程 的 ngx_shmtx lock 方 法 持 有 锁 的 方式 。 当 不 文 持 信号 量 时 ，ngx_shmtx lock 取 
锁 与 14.3.3 贡 中 介绍 的 目 旋 锁 是 一 致 的 ， 而 文 持 信号 量 后 ，ngx_shmtx lock 将 在 spin 指 定 的 一 
段 时 间 内 目 旋 等 竺 其 他 处 理 器 释放 锁 ， 如 采 达 到 spin 上 限 还 没有 获取 到 锁 ， 那 么 将 会 使 用 
sem_ wait 使 得 当前 进程 进入 睡眠 状态 ， 等 其 他 进程 释放 了 锁 内 核 后 才 会 唤醒 这 个 进程 。 当 
然 ， 在 实际 实现 过 程 中 ，Nginx 做 了 非常 巧妙 的 设计 ， 它 使 得 ngx_shmtx lock 方法 在 运行 一 段 
时 间 后 ， 如 果 其 他 进程 始终 不 放 奔 锁 ， 那 么 当前 进程 将 有 可 能 强制 性 地 获得 到 这 把 锁 ， 这 也 
是 出 于 Nginx 不 宜 使 用 阻 窗 进程 的 睡 虐 锁 方面 的 考虑 。 








14.8.1 文件 锁 实现 的 ngx_shmtx_ i 锁 
本 节 介 绍 如 何 通 过 文件 锁 实现 表 14-1 中 的 5 种 方法 (也 就 是 Nginx 对 fenmtl 系 统 调用 封 疙 过 
的 ngx trylock 包 、ngx lock 人 包 和 ngx unlock 季 方 法 实现 的 锁 )。 


ngx shmtx create 方 法 用 来 初始 化 ngx shmtx {t 互 斥 锁 ，ngx shmtx t 结 构 体 要 在 调用 
ngx_Shmtx_create 方 法 前 先行 创建 。 下 面 看 一 下 该 方法 的 源 代 码 。 





ngx int t ngx shmtx create(ngx shmtx 七 xmtXx void addr, u char name) { 





// 不 用 在 调用 


ngx_shmtx_create 方 法 前 先行 赋值 给 


ngx_shmtx 七 结构 体 中 的 成 员 
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if (mtx->name) { 


/* 如 果 


ngx shmtx 七 中 的 


name 成 员 有 值 ， 那 么 如 果 与 


name 参 数 相同 ， 意 味 着 


mtx 互 斥 锁 已 经 初始 化 过 了 ; 否则 ， 需 要 先 销毁 


mtx 中 的 互 斥 锁 再 重新 分 配 


mtx*/ 
if (ngx strcmp (name, mtx->name) == 0) { 


// 如 果 


name 参 数 与 
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ngx shmtx 七 中 的 


name 成 员 相 同 ， 则 表示 已 经 初始 化 了 


mtx->name = name; 


// 既然 曾经 初始 化 过 ， 证 明 


fd 句柄 已 经 打开 过 ， 直 接 返 回 成 功 即 可 


return NGX OK; 


/* 如 果 


ngx shmtx 七 中 的 


name 与 参数 


name 不 一 致 ， 说 明 这 一 次 使 用 了 一 个 新 的 文件 作为 文件 锁 ， 那么 先 调用 


ngx_shmtx_qestory 方 法 销毁 原文 件 锁 
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ngx shmtx destory (mtx); 


// 按照 


name 指 定 的 路 径 创 建 并 打开 这 个 文件 





mtx->fd = ngx open file(name, NGX FILE RDWR, NGX FILE CREATE OR OP 






































EN, NGX FILE DEFAULT ACCESS); if (mtx->fd 





// 一 旦 文件 因为 各 种 原因 (如 权限 不 够 ) 无 法 打开 ， 通 常会 出 现 无 法 运行 错误 





return NGX ERROR; 


/* 由 于 只 需要 这 个 文件 在 内 核 中 的 





INODE 信 息 ， 所 以 可 以 把 文件 删除 ， 只 要 


fd 可 用 就 行 


人 








if (ngx delete file (name) == NGX FILE ERROR) { 
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return NGX OK; 





ngx_shmtx_create 方 法 需要 确保 ngx_shmtx tt 结构 体 中 的 和 包 是 可 用 的 ， 它 的 成 功 执 行 是 使 用 
互 斥 锁 的 先决 条 件 。 


ngx shmtx destory 方 法 用 于 关闭 在 ngx shmtx_ create 方法 中 已 经 打开 的 乌 句 柄 ， 如 下 所 





void ngx shmtx destory(ngx shmtx 七 *mtx) { 


// 关闭 


ngx _shmtx 鞋 结 构 体 中 的 


fd 和 句 酉 





if (ngx Close file (mtx->fd) == NGX FILE ERROR) { 














ngx log error(NGX LOG ALERT, ngx cycle->log, ngx errno, ngx close file n " \"%s\" failed", mtx->name); 








ngx_shmtx trylock 方 法 试图 使 用 非 阻 堵 的 方式 获得 锁 ， 返 回 1 时 表示 获取 锁 成 功 ， 返 回 0 
表示 获取 锁 失 败 。 


DDN httpo://wWw inuxorobe, con 





ngx uint t ngx shmtx trylock(ngx shmtx 七 *mtx) { 





ngx :ery t. “Srey 


ngx_trylock fd 方法 实现 非 阻塞 互 斥 锁 的 获取 


err = ngx trylock fd(mtx=>fd); if (err == 0) { 
return 1; 
} 
// 如 果 
err 错 误 码 是 





NGX_EAGAIN， 则 表示 现在 锁 已 经 被 其 他 进程 持 有 了 


if (err == NGX EAGAIN) { 





过 合 蕊 了 六 衣 0: 记 


} 
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ngx 1og abort (err, ngx trylock fd n " %s failed", mtx->name); return 0; 





ngx_shmtx lock 方法 将 会 在 获取 锁 失 败 时 阻塞 代码 的 继续 执行 ， 它 会 使 当前 进程 处 于 睡 
眠 状态 ， 等 待 其 他 进程 释放 锁 后 内 核 唤醒 它 。 可 见 ， 它 是 通过 14.7 节 介绍 的 ngx lock 全 方法 
实现 的 ， 如 下 所 示 。 





void ngx shmtx lock(ngx shmtx t *mtx) { 


ngx err t “erry 


// ngx lock fd 方法 返回 


0 时 表示 成 功 地 持 有 锁 ， 返 回 


-1 时 表示 出 现 错误 
err = ngx lock fd(mtx->fd); if (err == 0) 1 
return; 
} 
ngx log abort (err, ngx lock fd n " gs failed", mtx->name); } 





ngx_shmtx_ lock 方法 没有 返回 值 ， 因 为 它 一 旦 返回 就 相当 于 获取 到 互 斥 锁 了 ， 这 会 使 得 
代码 继续 向 下 执行 。 
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ngx shmtx unlock 方 法 通过 调用 ngx unlock 人 方法 来 释放 文件 锁 ， 如 下 所 示 。 





void ngx shmtx unlock(ngx shmtx 七 *mtx) { 


nogx errt tt err; 


// 返回 
0 即 表示 释放 锁 成 功 
err = ngx unlock fd(mtx->fd); if (err == 0) { 
return; 
} 
ngx log abort (err, ngx unlock fd n " %s failed", mtx->name); } 





可 以 看 到 ，ngx shmtx t 互 斥 锁 在 使 用 文件 锁 实 现时 是 非常 简单 的 ， 它 只 是 简单 地 封装 了 
14.7 节 介绍 的 文件 锁 。 





14.8.2 ”原子 变量 实现 的 ngx shmtx tt 锁 





当 Nginx 判 断 当 前 操作 系统 文 持原 子 变 量 时 ， 将 会 优先 使 用 原子 变量 实现 表 14-1 中 的 5 种 
方法 〈 即 原子 变量 锁 的 优先 级 高 于 文件 锁 ) 。 不 过 ， 同 时 还 需要 判断 其 是 否 支 持 信 号 量 ， 
为 文 持 信 号 量 后 进程 有 可 能 进入 睡眠 状态 。 下 面 介绍 一 下 如 何 使 用 原子 变量 和 信和 号 量 来 实现 
ngx_shmtx t 互 斥 锁 ， 注 意 ， 它 比 文件 锁 的 实现 要 复杂 许多 。 




















ngx shmtx { 结 构 中 的 lock 原 子 变量 表示 当前 锁 的 状态 。 为 了 便于 理解 ， 我 们 还 是 用 接近 
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目 然 语 言 的 方式 来 说 明 这 个 锁 ， 当 lock 值 为 0 或 者 正 数 时 表示 没有 进程 持 有 锁 ;， 当 lock 值 为 负 
数 时 表示 有 进程 正 持 有 锁 〈 这 里 的 正 、 负 数 仅 相对 于 32 位 系统 下 有 符号 的 整 型 变量 ) 。 
Nginx 是 怎样 快速 判断 lock 值 为 “ 正 数 ”或 者 “负数 ”的 呢 ? 很 简单 ， 因 为 有 符号 整 型 的 最 高 位 是 
用 于 表示 符号 的 ， 其 中 0 表示 正 数 ，1 表 示人 负数 ， 所 以 ， 在 确定 整 型 val 是 负数 或 者 正 数 时 ， 





可 通过 判断 (val&0x80000000)==0 语 句 的 真 假 进 行 。 


下 面 看 一 下 初始 化 ngx shmtx t 互 斥 锁 的 ngx shmtx create 方 法 究竟 做 了 些 什么 事情 。 





{ 


ngx int t ngx shmtx create(ngx shmtx t *mtx, void addr, u char name) 





mtx->lock = addr; 


// 注意 ， 当 
Spin 值 为 


-1 时 ， 表 示 不 能 使 用 信号 量 ， 这 时 直接 返回 成 功 


if (mtx->spin == (ngx uint 七 ) -1) { 


return NGX OK” 


// spin 值 默认 为 


2048 


mtx->spin = 2048; 
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// 同时 使 用 信号 量 


#if (NGX HAVE POSIX SEM) 








// 以 多 进程 使 用 的 方式 初始 化 


sem 信 号 量 ， 


sem 初 始 值 为 


if (sem init(&mtx->sem, 1, 0) == -1) { 





ngx log error(NGX LOG ALERT, ngx cycle->log, ngx errno, "sem init() failed"); } else { 


// 在 信号 量 初始 化 成 功 后 ， 设 置 


semaphore 标 志 位 为 


mtx->semaphore = 1; 


#endif 


return NGX OK; 


中 INNNNNDNDD 人 








spin 和 和 semaphore 成 员 都 将 决定 ngx shmtx lock 了 阻塞 锁 的 行为 。 


ngx shmtx destory 方 法 的 唯一 上 日 的 就 是 释放 信 与 量 ， 如 下 所 示 。 





void ngx shmtx destory(ngx shmtx 七 *mtx) { 


// 支持 信号 量 时 才 有 代码 需要 执行 


#if (NGX HAVE POSIX SEM) 








/* 当 这 把 锁 的 


Spin 值 不 为 


(ngx_uint 七 ) -1 时 ， 且 初始 化 信号 量 成 功 ， 


semaphore 标 志 位 才 为 


if (mtx->semaphore) { 


// 销毁 信和 号 量 


if (sem destroy(&mtx->sem) == -1) { 
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ngx log error (NGX LOG ALERT, ngx cycle->log, ngx errno "sem destroy() failed"); } 


#endif 





以 非 阻塞 方式 获取 锁 的 ngx_shmtx trylock 方 法 较为 简单 ， 可 直接 判断 lock 原 子 变量 的 值 ， 
当 它 为 非 负数 时 ， 直 接 将 其 置 为 负数 即 表示 持 有 锁 成 功 。 怎 样 把 0 或 者 正 数 置 为 负数 呢 ? 很 
简单 ， 使 用 语句 vall0x80000000 即 可 把 非 负数 的 val 变 为 负数 ， 这 种 方法 效率 最 高 ， 即 直接 修 


改 val 的 最 高 符号 标志 位 为 1。 














ngx uint t ngx shmtx trylock(ngx shmtx 七 *mtx) { 





ngx atomic uint t val; 


// 取出 


lock 锁 的 值 ， 通 过 判断 它 是 否 为 非 负 数 来 确定 锁 状 态 


val = *mtx->lock; 


/* 如 果 


Val 为 


0 或 者 正 数 ， 则 说 明 没 有 进程 持 有 锁 ， 这 时 调用 
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ngx atomic cmp set 方法 将 


lock 锁 改 为 负数 ， 表 示 当 前 进程 持 有 了 互 斥 锁 


4 


return ((val & Ox80000000) == 0 && ngx atomic cmp set (mtx->lock, val, val | 0x80000000)); 1} 





@ 注意 ” (val&0x80000000)==0 是 一 行 语句 ， 而 ngx_atomic_cmp_set(mtx- 
>lockval,val | 0x80000000) 又 是 一 行 语句 ， 多 进程 的 Nginx 服 务 将 有 可 能 出 现 虽 然 第 1 行 语 句 执行 
成 功 〈 表 示人 锁 未 被 任何 进程 持 有 ) ， 但 在 执行 第 2 行 语句 前 ， 又 有 一 个 进程 拿 到 了 锁 ， 这 时 
第 2 行 语句 将 会 执行 失败 。 这 正 是 ngx_atomic_cmp_set 方 法 自身 先 判 断 lock 值 是 否 为 非 负数 val 
的 原因 ， 只 有 lock 值 为 非 负 数 val， 它 才 会 确定 将 lock 值 赋 为 负数 val|0x80000000 并 返回 1， 否 则 


返回 0 ( 详 见 14.3.2 节 ) 。 








阻塞 式 获 取 互 斥 锁 的 ngx_shmtx lock 方 法 较为 复杂 ， 在 不 文 持 信号 量 时 它 与 14.3.3 节 介绍 
的 上 自 旋 锁 几 乎 完全 相同 ， 但 在 支持 了 信号 量 后 ， 它 将 有 可 能 使 进程 进入 睡眠 状态 。 下 面 我 们 
分 析 一 下 它 的 操作 步 又 。 





void ngx shmtx lock(ngx shmtx t *mtx) { 
ngx uint t i, n; 
ngx atomic uint t val; 


// 没有 拿 到 锁 之 前 是 不 会 跳出 循环 的 
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/*lock 值 是 当前 的 锁 状 态 。 注 意 ， 


lock 一 般 是 在 共享 内 存 中 的 ， 它 可 能 会 时 刻 变 化 ， 而 


Val 是 当前 进程 的 栈 中 变量 ， 下 面 代 码 的 执行 中 它 可 能 与 


lock 值 不 一 致 


EA 
val = *mtx->lock; 
/* 如 果 
val 为 非 负 数 ， 则 说 明 锁 未 被 持 有 。 下 面试 图 通过 修改 
LocK 值 为 负数 来 持 有 锁 
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if ((val & 0x80000000) == 
&& ngx atomic cmp set (mtx->lock, val, val | Ox80000000)) { 


/* 在 成 功 地 将 


lock 值 由 原先 的 
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Val 改 为 非 负数 后 ， 表 示 成 功 地 持 有 了 锁 ， 


ngx_Shrmtx lock 方 法 结束 


*/ 


return; 


// 仅 在 多 处 理 器 状态 下 


spin 值 才 有 意义 ， 否 则 


PAUSE 指 令 是 不 会 执行 的 





if (ngx ncpu > 1) { 


// 循环 执行 


PAUSE， 检 查 锁 是 否 已 经 释放 





for (n= 1; n < mtx->spin; n <<= 1) { 


// 随 着 长 时 间 没 有 获得 到 锁 ， 将 会 执行 更 多 次 
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PAUSE 才 会 检查 锁 





for (i= 0; i < n; i++) { 


// 对 于 多 处 理 器 系统 ， 执 行 


ngx_cpu pause 可 以 降低 功 耗 


ngx cpu pause(); 1} 


// 再 次 由 共享 内 存 中 获得 


lock 原 子 变 量 的 值 


val = *mtx->lock; /* 检 查 
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lock 是 否 已 经 为 非 负 数 ， 即 锁 


LocK 原 子 变量 值 设 置 为 负数 来 表示 当前 进程 持 有 了 锁 
*] 


if ((val & 0x80000000) == 
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// 持 有 锁 成 功 后 立刻 返回 


return; 


// 支持 信号 量 时 才 继 续 执行 


#if (NGX HAVE POSIX SEM) 








// semaphore 标 志 位 为 


1 才 使 用 信号 量 


if (mtx->semaphore) { 


// 重新 获取 一 次 可 能 在 共享 内 存 中 的 





lock 原 子 变 量 


val = *mtx->lock; 
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// 如 果 


lock 值 为 负数 ， 则 


lock 值 加 上 


if ((val & Ox80000000) && ngx atomic cmp set (mtx->lock, val, val + 1)) { 


sem 的 值 ， 如 果 

sem 值 为 正 数 ， 则 

sem 值 减 

1， 表 示 拿 到 了 信号 量 互 斥 锁 ， 同 时 
Sem Wai 方法 返回 


0。 如 果 
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sem 值 为 


0 或 者 负数 ， 则 当前 进程 进入 睡眠 状态 ， 等 待 其 他 进程 使 用 


ngx_ shmtx unlock 方 法 释放 锁 (等待 


Sem 信 号 量变 为 正 数 ) ， 到 时 





Linux 内 核 会 重新 调度 当前 进程 ， 继 续 检 查 


Sem 值 是 否 为 正 ， 重 复 以 上 流程 


人 


while (sem wait (&mtx->sem) == -1) { 








ngx err t err; err = ngx errno; // 当 





EINTR 信 号 出 现时 ， 表 示 


sem wait 只 是 被 打 断 ， 并 不 是 出 错 





if (err != NGX EINTR) { 
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// 循环 检查 


lock 锁 的 值 ， 注 意 ， 当 使 用 信号 量 后 不 会 调用 


sched yield 


continue; 


#endif 


// 在 不 使 用 信号 量 时 ， 调 用 


sched _ yield 将 会 使 当前 进程 暂时 “让 出 ”处 理 器 


ngx sched yield(); 





可 以 看 到 ， 在 不 使 用 信号 量 时 (例如 ，NGX_HAVE_POSIX_SEM 宏 没 打开 ， 或 者 spin 的 
值 为 (ngx_uint -1) ，ngx_shmtx lock 方法 与 ngx_spinlock 方 法 非常 相似 ， 而 在 使 用 信和 号 量 后 
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将 会 使 用 可 能 让 进程 进入 睡眠 的 sem wait 方法 代 蔡 “让 出 ”处 理 器 的 ngx_sched_ yield 方法 。 这 
里 不 建议 在 Nginx worker 进 程 中 使 用 带 信号 量 的 ngx_shmtx_ lock 取 锁 方法 。 


ngx_shmtx_unlock 方 法 会 释放 锁 ， 虽 然 这 个 释放 过 程 不 会 阻 豆 进程 ， 但 设置 原子 变量 lock 
值 时 是 可 能 失败 的 ， 因 为 多 进程 在 同时 修改 lock 值 ， 而 ngx_atomic_cmp_set 方 法 要 求 参数 old 
的 值 与 lock 值 相同 时 才能 修改 成 功 ， 因 此 ，ngx_atomic_cmp_set 方 法 会 在 循环 中 反复 执行 ， 直 
到 返回 成 功 为 止 。 该 方法 的 实现 如 下 所 示 : 








void ngx shmtx unlock(ngx shmtx 七 *mtx) { 


ngx atomic uint 七 val,， old，wait; // 试图 循环 重 置 


lock 值 为 正 数 ， 此 时 务必 将 互 斥 锁 释 放 


for (;; ) { 


// 由 共享 内 存 中 的 


lock 原子 变量 取出 锁 状 态 


old = *mtx->lock; 


// 通过 把 最 高 位 置 为 


0， 将 
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LocKk 变 为 正 数 


wait = old & 0x7fffffff; // 如 果 变 为 正 数 的 


lock 不 是 

0， 则 减 去 

| 
val = wait wait - 1 : 0; 
// 将 


lock 锁 的 值 设 为 非 负 数 


val 
if (ngx atomic cmp set (mtx->lock, old, val)) { 
// 设置 锁 成 功 后 才能 跳出 循环 ， 否 则 将 持续 地 试图 修改 
lock 值 为 非 负 数 


break; 
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#if (NGX HAVE POSIX SEM) 


/* 如 果 


lock 锁 原先 的 值 为 


0， 也 就 是 说 ， 并 没有 让 某 个 进程 持 有 锁 ， 这 时 直接 返回 ; 或 者 ， 


semaphore 标 志 位 为 


0， 表 示 不 需要 使 用 信号 量 ， 也 立即 返回 


*y 


if (wait == 0 || !mtx->semaphore) { 
return; 
} 
/* 通 过 


as i 


sem post 将 信号 量 


sem 加 
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1， 表 示 当 前 进程 释放 了 信号 量 互 斥 锁 ， 通 知 其 他 进程 的 


sem wait 继 续 执行 


*/ 


if (sem post(&mtx->sem) == -1) { 





ngx log _ error (NGX LOG ALERT, ngx cycle->log, ngx errno, "sem post() failed while wake shmtx"); } 


#endif 











由 于 原子 变量 实现 的 这 $ 种 互 斥 锁 方 法 是 Nginx 中 使 用 最 广泛 的 同步 方式 ， 当 需要 Nginx 
文 持 数 以 万 计 的 并 发 TCP 请 求 时 ， 通 常 都 会 把 spin 值 设 为 mgx_uint D-1。 这 时 的 互 斥 锁 在 取 
锁 时 都 会 采用 目 旋 锁 ， 对 于 Nginx 这 种 单 进 程 处 理 大 量 请 求 的 场景 来 说 是 非常 适合 的 ， 能 够 
大 量 降低 不 必要 的 进程 间 切 换 带 来 的 消耗 。 














TiNNinNnn http://wWwWw linuxorobe.con 





14.9 ”小 结 








Nginx 是 一 个 能 够 并 发 处 理 儿 十 万 甚至 几 百 万 个 TCP 连 接 的 高 性 能 服务 右 ， 因 此 ， 在 进行 
进程 间 通 信 时 ， 必 须 充 分 考虑 到 不 能 过 分 影响 正 冰 请 求 的 处 理 。 例 如 ， 使 用 14.4 节 介绍 的 套 
接 字 通信 时 ， 套 接 字 都 被 设 为 了 无 阻塞 模式 ， 防 止 执行 时 阻 竖 了 进程 导致 其 他 请 求 得 不 到 处 
理 ， 又 如 ，Nginx 封 装 的 锁 都 不 会 直接 使 用 信号 量 ， 因 为 一 旦 获取 信和 号 量 互 斥 锁 失 败 ， 进 程 
就 会 进入 睡眠 状态 ， 这 会 导致 其 他 请 求 “ 饿 死 ”。 











当 用 户 开 及 复杂 的 Nginx 模 块 时 ， 可 能 会 涉及 不 同 的 worker 进 程 间 通信 ， 这 时 可 以 从 本 
章 介 绍 的 进程 间 通 信和 方式 上 进行 选择 ， 从 使 用 上 说 ，ngx_shmtx t 互 斥 锁 和 共享 内 存 应 当 是 第 
三 方 Nginx 模 块 最 常用 的 进程 间 通 信 方 式 了 ，ngx_shmtx t 互 斥 锁 在 实现 中 充分 考虑 了 是 否 引 
发 睡 虐 的 问题 ， 用 户 在 使 用 时 需要 明确 地 判断 出 是 否 会 引发 进程 睡眠。 当然 ， 如 果 不 使 用 
Nginx 封 装 过 的 进程 间 通 信 方 式 ， 则 需要 注意 跨 平 台 ， 以 及 是 舍 会 阻 窗 进程 的 运行 等 问题 。 
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第 15 章 ”变量 


Nginx 有 许多 功能 体现 在 nginx.conf 这 个 脚本 式 的 配置 文件 里 ， 这 些 配 置 项 的 格式 五 花 八 
门 、 风 格 各 寞 ， 原 因 是 它们 都 由 各 Nginx 模 块 自 定 义 ， 并 没有 什么 统一 的 标准 ， 这 在 第 4 章 已 
经 提 及 。 然 而 ， 我 们 可 以 看 到 许多 广 为 流传 的 配置 项 ， 它 们 都 支持 在 一 行 配置 中 ， 加 入 诸如 
$ 符 写 紧 跟 字符 串 的 方式 ， 试 图 表达 实时 请 求 中 茶 些 共 性 参数 ， 就 像 编 程 语言 中 的 变量 与 
值 ， 这 使 得 Nginx 的 使 用 成 本 、 学 习 成 本 大 幅 降低 ，Nginx 用 户 仅 在 nginx.conf 中 做 些 修 改 就 可 
以 拥有 更 复杂 的 功能 


























例如 在 指定 access.log 请 求 访 问 日 志 格 式 的 时 候 ，ngx_http_log_module 模 块 就 允许 Nginx 管 
理 员 非常 灵活 地 定义 日 志 格 式 ， 以 方便 诸如 awstats 等 第 三 方 统计 工具 能 够 依据 个 性 化 的 日 志 
为 站 长 们 分 析出 有 意义 的 结果 来 ， 例 如 : 


log format main "Sremote addr S$remote user ' 

' [$time local] "$request" $status ' 
'$Shost $body bytes sent S$gzip ratio "$nttp referer™" ' 
'"$http user agent" "$http x forwarded for"'; 

access log logs/access.log main; 








又 比如 ， 在 限制 用 户 的 请 求 访问 速度 时 ， 怎 样 判 断 不 同 的 TCP 连 接 是 来 自 于 同一 用 户 的 
请 求 呢 ? 有 些 场 景 是 依据 TCP 连 接 的 对 端 耻 ， 但 如 果 客 户 端 是 通过 代理 服务 器 访问 则 又 不 可 
靠 。 还 有 些 场景 会 依据 http 头 部 的 cookie， 甚 至 更 小 众 的 需求 可 以 依据 URI 或 者 URIL 人 参数 。 
ngx_http_limit req_module 模 块 提供 这 样 复 杂 的 功能 以 满足 广泛 的 场景 ， 所 依据 的 也 是 在 
nginx.conf 配 置 文件 中 提供 $ 这 样 的 配置 项 以 描述 请 求 ， 比 如 可 以 依据 对 端正 进行 限 速 : 


limit req zone $binary remote addr zone=one:10m rate=1lr/s; 


在 这 两 个 例子 中 ， 其 实 都 是 在 模块 中 使 用 Nginx 定 义 的 内 部 变量 ， 像 $remote addr 这 样 的 
参数 。 这 些 内 部 变量 在 Nginx 官 方 代码 中 定义 ， 目 前 是 在 ngx_http_ variables.c 文 件 的 


_variables 数 组 中 定义 的 。 在 本 章 中 ， 我 们 首先 学 习 如 何在 自己 的 模块 中 使 用 已 
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有 的 常用 内 部 变量 ， 使 模块 具备 类 似 access_log 或 者 limit_req 模 块 在 nginx.conf 文 件 中 配置 内 部 
变量 的 功能 。 





除了 要 能 够 使 用 已 有 变量 外 ， 我 们 还 需要 具备 定义 新 的 内 部 变量 的 能 力 ， 使 其 他 Nginx 
模块 也 能 够 使 用 我 们 定义 的 新 变量 。 这 些 新 变量 与 现 有 的 内 部 变量 是 一 致 的 ， 也 是 在 使 用 到 
的 时 候 开始 解析 、 绥 存 。 


官方 的 ngx_http rewrite module 模 块 还 提供 了 配置 文件 脚本 式 语法 的 执行 ， 人 允许 在 配置 文 
件 里 直接 定义 全 新 的 变量 ， 由 于 它 不 在 代码 中 而 是 在 nginx.conf 中 定义 ， 所 以 称 其 为 外 部 变 
量 ， 例 如 : 





set S$parameterl "abcd"; 
set $memcached key "$uri$args"; 











本 章 将 先 以 一 个 简洁 的 例子 描述 使 用 变量 的 基本 开发 方法 ， 再 通过 说 明 Nginx 对 变量 的 
实现 原理 使 读者 更 透彻 地 理解 这 种 开发 方式 ， 进 而 再 扩展 这 个 例子 ， 帮 助 读者 更 灵活 地 和 掌握 
变量 的 使 用 。 最 后 ， 则 会 以 一 个 简单 的 外 部 变量 配置 为 例 ， 介 绍 脚本 引擎 是 怎样 编译 、 执 行 
脚本 指令 的 。 
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15.1 使 用 内 部 变量 开发 模块 





使 用 Nginx 预 定义 的 内 部 变量 的 方法 非常 简单 ， 将 你 需要 使 用 的 变量 名 作为 参数 传 入 
《例如 在 解析 配置 文件 的 时 候 ) ， 调 用 ngx http_get variable index 方 法 ， 获 取 到 这 个 变量 名 
对 应 的 索引 值 ， 如 下 : 





ngx int t 


ngx http get variable index(ngx conf t cf, ngx str t name); 


字符 串 ngx_str {类 型 的 name 束 是 变量 名 ， A 的 ， 返 
回 值 就 是 这 个 变量 的 索引 值 。 关 于 变量 的 索引 在 15.2 市 再 详细 说 明 ， 通 常 来 说 ， 使 用 索引 值 
而 不 是 变量 字符 串 来 获取 变量 值 是 个 好 主意 ， 它 会 加 快 Nginx 的 执行 速度 。 事 实 上 ，Nginx 提 
供 了 两 种 方式 来 找 出 要 使 用 的 内 部 变量 ， 一 种 是 索引 过 的 变量 ， 可 直接 由 数组 下 标 找 到 元 
素 ; 为 一 种 是 添加 a 到 散 列 表 的 变量 ， 需 要 将 字符 串 变 量 名 由 散 列 方法 算出 散 列 值 ， 再 从 散 列 
表 中 找 出 元 素 ， 遇 到 元 系 神 突 时 需要 过 历 开 散 列 表 的 槽 位 链表 《〈 参 见 第 7 章 ) 。 可 见 ， 哪 个 
更 快 是 一 目 了 然 的 ， 当 然 ， 索 引 变量 要 比 散 列 变量 占用 多 一 后 的 内 存 。 
































保存 这 个 索引 值 〈 例 如 在 你 的 配置 结构 体 中 ) 。 处 理 请 求 时 ， 则 使 用 这 个 索引 值 ， 调 用 
ngx_http_get indexed variable 方 法 获取 到 变量 的 值 ， 如 下 : 





ngx http variable value t * 


ngx http get indexed variable(ngx http request t *r, ngx uint 七 index) 





index 参 数 束 是 ngx_http_get_variable_index 方 法 获得 的 变量 索引 ， 而 rf 参数 当然 束 是 请 求 
了 ， 每 一 个 变量 的 值 都 随 着 请 求 的 不 同 而 变化 。 方 法 的 返回 值 就 是 变量 值 ， 当 然 返 回 NULL 
即 没有 解析 出 变量 。 
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最 基本 的 使 用 变量 方法 就 是 如 此 简单 ， 我 们 先 不 探究 更 灵活 的 使 用 方式 和 数据 成 员 的 详 
细 意 义 ， 先 以 一 个 可 运行 的 例子 来 给 不 熟悉 的 读者 朋友 一 个 直观 的 认识 。 


在 配置 文件 中 使 用 变量 可 以 提高 模块 功能 的 灵活 性 ， 也 是 Nginx 模 块 的 常用 手法 。 就 如 
第 4 章 所 述 ，nginx.conf 中 的 配置 项 格式 如 何 设计 完全 是 模块 的 自由 ， 即 使 把 配置 项 设计 得 无 
比 另 类 也 不 影响 我 们 使 用 内 部 变量 。 然 而 ， 符 合 惯例 的 设计 会 降低 使 用 、 维 护 成 本 ， 因 此 ， 
最 好 还 是 在 配置 文件 中 使 用 变量 时 在 变量 名 前 加 上 “$”* 符 号 。 本 节 的 这 个 例子 将 实现 以 下 功 
能 : 在 配置 文件 中 指定 某 些 location 下 的 请 求 来 临时 ， 必 须根 据 配置 项 myallow 指 定 的 变量 及 
其 判定 值 来 决定 请 求 是 否 被 允许 。 比 如 ， 如 果 在 nginx.conf 中 加 入 下 面 这 段 配 置 ， 这 个 模块 就 
会 通过 myallow 选 项 决定 某 些 请 求 必 须 具备 testHeader:xxx 这 样 的 http 头 部 才能 放行 ， 有 些 请 求 
则 必须 来 自 于 卫 10.69.50.199 才 能 放行 ， 只 要 是 Nginx 定 义 的 内 部 变量 都 可 以 放 在 myallow 中 。 

















location /testl { 


myallow S$http testHeader xxx; 


root /www/testl1; 


location /test2 { 


root /www/test2; 


location / { 


root /Www; 


myallow Sremote addr 10.69.50.199; } 





be 





作用 ， 当 有 具备 相应 的 如 $varaible 内 部 变量 ， 且 其 值 为 myallow 的 第 2 个 参数 时 ， 这 个 请 求 才能 
继续 进行 ， 否 则 返回 403 错 误 码 。 





笔者 构造 这 个 例子 虽然 试图 简单 到 只 使 用 http 内 部 变量 ， 却 仍然 使 用 到 了 第 4 章 的 配置 项 
解析 、 第 11 章 的 HTTP 访问 控制 阶段 ， 读 者 阅读 时 各 有 疑问 可 翻阅 这 两 章 回 顾 。 











15.1.1 定义 模块 


这 次 把 模块 名 取 为 ngx http testvariable module， 通 过 config 配 置 文件 把 模块 编译 进 Nginx 
的 方法 参见 第 3 章 ， 这 一 小 市 仅 定 义 表 示 模 块 的 数据 结构 ， 如 下 : 














ngx module t ngx http testvariable module = 





NGX MODULE V1, 





&ngx http testvariable module ctx, ngx http testvariable commands, 

















NGX_ HTTP MODULE, /* module type */ 
NULL, /* init master */ 
NULL, /* init module */ 
NULL, /* init process */ 
NULL, /* init thread */ 
NULL, /* exit thread */ 
NULL, /* exit process */ 
NULL, /* exit master */ 


中 phttp:// Ww | 1 NUxorobe. con 








这 个 模块 是 一 个 普通 http 模 块 ， 所 以 不 需要 在 通用 的 master、worker 进 程 启 动 过 程 中 引入 
回调 方法 ， 而 是 在 negx http testvariable module_ctx 中 决定 了 在 htp 人 配置 解析 时 的 调用 方式 ， 
1$.1.2 节 会 描述 这 一 结构 体 的 定义 。ngx http_ testvariable_ commands 描 述 了 模块 如 何 解析 配置 
项 ， 在 15.1.3 节 会 详细 描述 


15.1.2 ”定义 http 模 块 加 载 方 式 


ngx_http_testvariable module_ ctx 的 定义 如 下 : 





static ngx http module t ngx http testvariable module ctx = 








// 不 需要 在 解析 配置 项 前 做 些 什么 。 如 果 需 要 添加 新 变量 ， 则 必须 在 这 个 回调 方法 中 实现 


NULL, /* preconfiguration */ 


// 解析 配置 完毕 后 会 回调 


ngx http mytest _ init 
ngx http mytest init, /* postconfiguration */ 


// myallow 配 置 不 能 存在 于 


http{} 和 
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SerVer{} 配 置 下 ， 所 以 通常 下 面 这 


4 个 回调 方法 不 用 实现 














NULL, /* create main configuration */ 
NULL, /* init main configuration */ 
NULL, /* create server configuration */ 
NULL, /* merge server configuration */ 
// 生成 存放 
location 下 
myallow 配 置 的 结构 体 
ngx http mytest create loc conf, /* create location configuration */ 








// 因为 不 存在 合并 不 同 级 别 下 冲突 的 配置 项 的 需求 ， 所 以 不 需要 


merge 方 法 


口 由 掉 岂 有 有 和 所 掉 由 http' /wNv inuxorobe. con 





NULL /* merge location configuration */ 





这 个 定义 表明 ，http 配 置 项 解析 完毕 后 需要 调用 ngx http mytest init 方 法 ， 因 为 在 这 个 方 
法 中 ， 我 们 将 会 把 ngx http testvariable module 模 块 加 入 到 请 求 的 处 理 流程 中 ;， 而 
ngx_http_mytest_create_loc_conf 回 调 方法 负责 生成 存储 配置 的 ngx_myallow_loc_conf t 结 构 体 : 





typedef struct { 


人 
i 
ba 
hd 


variable 的 索引 值 


int variable index; 


// myallow 配 置 后 第 


1 个 参数 ， 表 示 待 处 理 变 量 名 


ngx_Str t variable; 


// myallow 配 置 后 第 


2 个 参数 ， 表 示 变 量 值 必须 为 
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equalvalue 才 能 放行 请 求 


ngx_ str t equalvalue; 


} ngx myallow loc conf t; 











ngx_http_mytest_create loc_conf 方 法 只 是 负责 在 每 个 location 下 生成 
ngx_myallow_ loc_conf t 结 构 体 ， 所 以 一 如 既往 的 简单 : 





static void 大 


ngx http mytest create loc conf (ngx conf 七 *cf) { 





ngx myallow loc conf 七 *conf; 
conf = ngx pcalloc (cf->pool, sizeof (ngx myallow loc conf t)); if (conf == NULL) { 


return NULL; 


// 没有 出 现 


myallow 配 置 时 


variable index 成 员 为 


conf->variable index = - 
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return conf; 





ngx_http_mytest_init 方 法 用 来 把 处 理 请 求 的 方法 ngx_http_mytest_handler 加 入 到 Nginx 的 11 个 
HTTP 处 理 阶段 中 ， 由 于 我 们 是 需要 控制 请 求 的 访问 权限 ， 因 此 会 把 它 加 入 到 
NGX HTTP ACCESS PHASE 阶 段 中 ， 如 下 : 








static ngx int t 


ngx http mytest init(ngx conf t *cf) 


ngx http handler pt 六 


ngx http core main conf 七 *cmcf; 





// 取出 全 局 唯一 的 核心 结构 体 


ngx http core main conf t 





cmcf = ngx http conf get module main conf(cf, ngx http core module); // 在 





cmcf->phases [NGX HTTP ACCESS PHASE] 阶 段 添加 处 理 方法 








h = ngx array push(&cmcf->phases[NGX HTTP ACCESS PHASE] .handlers); if (hn == NULL) { 











return NGX ERROR; 
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// 处 理 请 求 的 方法 是 本 模块 的 


ngx http mytest handler 方 法 


*h = ngx http mytest handler; 


return NGX OK; 





15.1.3 ”解析 配置 中 的 变量 


解析 配置 项 的 ngx http_testvariable commands 数 组 定义 如 下 : 





static ngx command t ngx http testvariable commands[] = 


ngx string ("myallow"), 


// 配置 项 只 能 存在 于 
location 内 ， 且 只 能 有 


2 个 参数 
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NGX HTTP LOC CONF | NGX CONF TAKE2, ngx http myallow, 














NGX HTTP LOC CONF OFFSET, 








NULL 


ngx null command 





解析 myallow 配 置 项 时 完全 没有 使 用 预 置 的 解析 方法 ， 全 靠 新 定义 的 negx_http myallow 方 
法 。 由 于 我 们 把 配置 项 定义 为 : 





myallow S$remote addr 10.69.50.199; 





所 以 ， 解 析 时 第 1 个 参数 需要 确认 第 1 个 字 答 必须 是 以 “$” 符 写 开 始 ， 之 后 的 字符 串 必须 
是 一 个 已 经 定义 的 变量 ， 第 2 个 参数 则 做 普通 字符 串 处 理 ， 如 下 : 








static char * 
ngx http myallow (ngx conf t * cf, ngx command t cmd, void conf) { 
ngx_ str 七 *value; 
ngx myallow loc conf t *macf = conf; 
Value = cf->args->elts; 


// myallow 只 会 有 
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2 个 参数 ， 加 上 其 自身 ， 


cf->args 应 有 





3 个 成 员 
if (cf->args->nelts != 3) { 
return NGX CONF ERROR; 
} 
// 第 


1 个 参数 必须 是 


$ 打 头 的 字符 囊 


if (value[1] .data[0] == '$') { 


// 去 除 第 


LA 
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value[l1] .len--; 


Value[1] .datat++; 





// 获取 变量 名 在 


Nginx 中 的 索引 值 ， 加 速 访 问 





macf->variable index = ngx http get variable index(cf, &value[1]); if (macf->variable indqex == NGX_ERROI 





return NGX CONF ERROR; 


macf->variable = value[1]; 


} else { 





return NGX CONF ERROR; 


// 保存 


myallow 的 第 
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2 个 参数 


macf->equalvalue= value[2]; 


return NGX CONF OK; 








这 样 ， 每 个 location 下 都 有 的 ngx myallow loc conf t 结 构 体 就 存放 了 可 能 存在 的 这 两 个 
参数 ， 留 待 处 理 请 求 时 使 用 。 


1$.1.4 ”处 理 请 求 


ngx_http_mytest_init 方 法 已 经 决定 http 请 求 到 达 Nginx 后 ， 将 会 在 
NGX_HTTP_ACCESS_PHASE 阶 段 按照 模块 顺序 调用 到 这 个 自 定义 的 ngx_http_mytest_handler 
方法 。 在 这 个 方法 中 ， 我 们 首先 需要 取出 请 求 选用 的 location 下 的 ngx_myallow_loc_conf t 结 
构 体 ， 它 表明 了 location 下 是 否 具 有 myallow 配 置 项 一 一 这 由 variable index 是 人 否 为 -1 决定 。 接 
着 ， 调 用 ngx http_get indexed_variable 方 法 取出 做 了 索引 的 变量 ， 再 比较 变量 的 值 是 否 乓 
equalvalue 字 符 串 完全 相同 ， 奉 相同 则 权限 判断 阶段 通过 ， 人 否则 返回 403 拒 绝 请 求 。 方 法 实现 
如 下 : 























static ngx int t ngx http mytest handqler (ngx http request t *r) { 





ngx myallow loc conf t *conf; 
ngx http variable value t xVV7 


// 先 取 到 当前 
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location 下 本 模块 的 配置 项 存储 结构 体 


conf = ngx http get module loc confl(r, ngx http testvariable module); if (conf == NULL) ({ 





return NGX ERROR; 





// 如 果 


location 下 没有 


myallow 配 置 项 ， 放 行 请 求 


if (conf->variable index == -1) { 





return NGX DECLINED; 











// 根据 索引 过 的 
variable inqex 下 标 ， 快 速 取 得 变量 值 


VV 


FF Ft Fp pa tt/ WhinNuxorober con 





return NGX HTTP FORBIDDEN 





// 比较 变量 值 是 否 与 


conf->equalvalue 相 同 ， 完 全 相同 才 会 放行 请 求 


if (vv->len == conf->equalvalue.len && 0 == ngx strncmp (conf->equalvalue.data,vv->data,vv->len)) { 





return NGX DECLINED; 











// 否则 ， 返 回 


403 拒 绝 请 求 继续 向 下 执行 


return NGX HTTP FORBIDDEN; 








如 此 ， 这 个 简单 的 模块 就 开发 完成 了 。 这 个 例子 很 简单 ， 仅 用 于 快速 上 手 ， 使 用 变量 的 
更 多 功能 前 我 们 必须 先 理 清 变量 工作 的 原理 。 
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15.2 ”内 部 变量 工作 原理 





理解 内 部 变量 的 设计 要 从 其 应 用 场景 入 手 。 顾 名 思 义 ,“ 内 部 ”变量 是 在 Nginx 的 代码 内 
部 定义 的 ， 也 就 是 说 ， 它 是 由 Nginx 模 块 在 C 代 码 中 定义 的 。 读 者 对 C 语 言 应 该 是 比较 熟悉 
的 ， 变 量 通 党 有 “声明 “定义 “赋值 “使 用 ”这 4 个 阶段 ， 而 上 面 所 说 的 定义 ， 实 际 上 更 
像 是 C 语 言 里 的 声明 ， 为 什么 呢 ? 因为 现在 只 是 说 明 有 这 么 一 个 变量 ， 而 没有 实际 分 配 用 于 
存储 变量 值 的 内 存 。 什 么 时 候 分 配 存储 变量 值 的 内 存 空 间 呢 ? 只 有 对 变量 赋值 的 时 候 ! 这 有 
两 个 原因 ， 一 是 变量 值 的 大 小 是 不 确定 的 ， 提 前 分 配 会 导致 内 存 浪 费 或 者 不 必要 的 内 存 找 
贝 ; 二 是 一 个 变量 可 能 在 很 多 场景 的 请 求 中 是 得 不 到 使 用 的 ， 提 前 分 配 是 不 必要 的 。 接 着 ， 
Nginx 框 以 会 从 性 能 的 角度 考虑 ， 将 所 有 内 部 变量 生成 散 列 表 ， 同 时 也 允许 各 个 模块 将 它们 
各 目 需要 的 变量 索引 到 一 个 数组 中 ， 加 快 访问 速度 。 























在 请 求 到 来 时 ，Nginx 对 变量 的 赋值 通常 是 采取 “用 时 赋值 ”的 策略 ， 也 就 是 说 ， 只 有 当 
菏 个 模块 试图 取 变 量 的 值 时 才 会 对 变量 进行 赋值 ， 而 不 是 接收 了 完整 的 HITP 头 部 后 就 开始 
解析 变量 。 当 然 ， 后 者 这 种 提前 赋值 更 符合 直观 理解 ， 但 是 绝 大 部 分 变量 就 是 这 么 设计 的 ， 
为 什么 呢 ?” 因 为 Nginx 是 一 个 极度 退 求 性 能 、 应 用 场景 单一 的 平台 ， 它 主要 用 于 Web 前 痢 ， 许 
多 Nginx 模 块 各 自负 员 着 不 同 的 请 求 ， 因 此 ， 对 于 每 个 请 求 都 去 解析 一 过 所 有 的 变量 ， 这 个 
代价 就 有 些 大 了 ， 反 而 是 对 于 一 个 请 求 而 言 ， 首 次 使 用 一 个 变量 时 才 去 解析 、 给 它 赋值 、 绥 
存 变量 值 ， 之 后 就 直接 取 组 人 存 值 ， 这 种 方式 性 能 高 得 多 ， 有 点 像 Linux 进 程 fork 时 的 “copy on 
write"， 原 因 都 是 一 个 请 求 多 半 只 使 用 全 部 变量 的 一 小 部 分 。 


























使 用 变量 时 ，Nginx 提 供 了 两 种 方式 找到 变量 : 一 是 根据 索引 值 直 接 找到 数组 里 的 相应 
变量 ， 二 是 根据 变量 名 字符 串 hash 出 的 散 列 值 ， 依 据 散 列表 找到 相应 的 变量 。 没 有 第 3 种 方 
式 ， 因 此 ， 如 果 我 们 定义 了 一 个 变量 ， 但 设 定 为 不 能 hash 进 入 散 列 表 ， 同 时 ， 使 用 该 变量 的 
模块 又 没有 把 它 加 入 索引 数组 ， 那 么 这 个 变量 是 无 法 使 用 的 。 
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15.2.1 何 时 定义 变量 





开发 Nginx 模 块 时 ， 什 么 时 候 、 在 哪个 回调 方法 里 定义 变量 呢 ? 这 当然 不 是 随意 的 ， 因 
为 变量 的 赋值 等 许多 工作 都 是 由 Nginx 框 架 来 做 的 ， 所 以 Nginx 的 HTTP 框 架 要 求 : 所 有 的 
HTTP 模 块 都 必须 在 ngx_http_module 结构 体 中 的 preconfiguration 回 调 方 法 中 定义 新 的 变量 。 
为 什么 要 在 这 里 定义 变量 呢 ? 我 们 回顾 第 10 半 HTTP 框 架 的 初始 化 流程 ， 图 10-10 为 了 使 主流 
程 更 清晰 忽略 了 变量 的 处 理 ， 我 们 从 图 10-10 中 第 3 步 创 建 配置 结构 体 开始 ， 给 出 变量 的 初始 
化 流程 图 ， 如 图 15-1 所 示 。 








简单 解释 图 1S$-1 里 各 个 步骤 与 变量 间 的 关系 : 


1) 调用 各 HTTP 模 块 的 create (main/src/loc) conf 方 法 ， 用 于 第 3 步 解 析 配 置 项 时 存放 配 
置 参 数 。 也 得 有 个 地 方 存放 配置 文件 中 的 变量 名 或 者 索引 ! 








2) 按照 所 有 HTTP 模 块 的 顺序 ， 调 用 它们 的 preconfiguration 方 法 (如 果实 现 的 话 ) 。 要 


想 定义 变量 ， 这 是 唯一 的 机 会 。 
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) 调用 各 HTTP 模 块 的 create_(main/srec/loc)_con{ 方 法 用 于 存放 解析 出 的 配置 项 


2 ) 调用 各 HTTP 模 块 的 preconfiguration 方 法 ， 可 引入 新 变量 


2.1 ) ngx_http_core_module 模 块 在 这 一 步 中 添加 ngx_http_core_variables 核 心 变 量 


2.2 ) 其 他 模块 依次 在 preconfiguration 方 法 中 可 能 加 入 新 的 变量 


) 开始 解析 、 处 理 http{.…} 据 下 的 所 有 配置 项 


3.1 ) 各 模块 解析 配置 的 方法 中 ， 可 能 会 将 某 个 变量 索引 化 


4 ) 依次 调用 HTTP 模 块 的 postconfiguration 方 法 使 模块 介入 HTTP 处 理 阶 段 中 


5 ) 调用 ngx_http_variables_init_vars 方 法 初始 化 所 有 变量 


5.1 ) 检查 索引 变量 的 合法 性 ， 并 设置 其 解析 方法 


5.2 ) 初始 化 索引 过 的 http_、sent_http_、upstream_http_、cookie_、arg_ 变 量 


3 ) 将 需要 散 列 的 变量 构造 出 静态 散 列 表 





全 


图 15-1 HTTP 变量 的 初始 化 


中 让 站 站 中 让 让 让 站 六 htt po: // www | i nuxorobe. con 





2.1) HTTP 模 块 中 ，ngx http_core _ module 模块 是 排名 第 1 的 ， 所 以 会 首先 执行 它 的 
preconfiguration 方 法 (实际 为 ngx http core preconfiguration 方 法 ) : 








static ngx http module 七 ngx http core module ctx = { 
ngx http core preconfiguration, /* preconfiguration */ 





}; 








而 这 个 方法 中 其 实 束 干 了 一 件 事 : 调用 ngx_http_variables_add core_vars 方 法 ， 把 用 于 存 
放 变 量 的 结构 体 初始 化 ， 再 将 Nginx 核 心 变 量 加 入 准备 hash 的 数组 variables keys 中 。 核 心 变量 
可 以 在 http://nginx.org/cn/docs/http/ngx http core module.html#variables 页 面 中 查看 ， 这 里 不 再 
重复 。 


在 15.1 市 的 例子 中 我 们 使 用 的 ee 际 上 就 是 ngx_http_core_module 模 块 定 
义 的 ， 它 通过 ngx http_ core variables 数 组 有 这 么 一 行 定 义 代码 : 





static ngx http variable t ngx http core variables[] = { 
{ ngx string("remote addr"), NULL, 
ngx http variable remote addr, 0, 0, 0 1}, 

} 








ngx http variables add core Vars 方 法 会 将 ngx_http_core_variables 数 组 里 的 所 有 核心 变量 
添加 a 到 Nginx 框 架 中 。 下 一 节 我 们 再 谈 这 个 过 程 是 怎样 进行 的 。 





2.2) 在 2.1 步 之 后 ， 其 他 HTTP 模 块 才 可 以 在 各 自 的 preconfiguration 方 法 中 加 入 自 定义 的 
内 部 变量 ，15.3 节 中 有 一 个 简单 的 例子 。 


3) 解析 配置 文件 http 旬 块 中 的 配置 项 ， 根 据 配置 项 名 称 找到 其 对 应 模块 的 
ngx_command t 结 构 体 ， 根 据 解析 方法 来 处 理 配置 项 。 


3.1) 需要 使 用 变量 的 模块 ， 通 常会 在 解析 配置 的 这 一 步 中 将 竺 使 用 的 变量 索引 化 。 为 
什么 呢 ? 因为 变量 索引 化 是 有 代价 的 ， 所 有 索引 化 的 变量 都 会 导致 存储 请 求 的 结构 体 
ngx_http request_t 增 加 内 存 占用 。 而 索引 化 又 是 有 好 处 的 ， 它 的 算法 复杂 上 度 是 O(D)， 而 使 用 
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散 列 表 则 先 需要 hash 出 散 列 值 ， 再 需要 处 理 散 列 桶 冲突 后 的 链表 壳 历 问题 。 那 么 ， 是 人 否 索引 
变量 就 与 server、location 配 置 相 关 了 ， 上 所 以 只 有 确定 会 用 到 变量 的 请 求 才 进行 索引 ， 这 样 通 
币 都 把 是 否 使 用 变量 交 给 配置 项 决定 。 


4) 调用 各 HTTP 模 块 的 postconfiguration 方 法 。 这 时 解析 完 配 置 了 ， 初 始 化 完 变 量 了 ， 这 
里 会 决定 模块 怎样 介入 到 HTTP 请 求 的 处 理 中 。 








5) 调用 ngx_http_variables _init_ vars 方 法 初始 化 HITP 变 量 。 这 一 方法 主要 包括 3 个 子 步 





5.1) 一 个 变量 是 否 进行 索引 ， 应 该 由 使 用 它 的 模块 决定 ， 而 不 是 由 定义 它 的 模块 决 
定 。 这 样 束 可 能 带 来 冲突 ， 如 果 使 用 模块 索引 了 一 个 变量 ， 其 实 却 没有 其 他 模块 定义 它 上 怎么 
办 ? 或 者 说 ， 有 模块 定义 了 它 ， 但 是 这 个 模块 没有 编译 进 Nginx 怎 么 办 ?所 以 ， 
ngx_http_variables_init_vars 方 法 肖 先 要 确保 索引 了 的 变量 都 是 合法 的 : 索引 过 的 变量 必须 是 

义 过 的 ; 其次， 使 用 索引 变量 的 模块 只 知道 索 引 某 个 变量 名 ， 此 时 需要 把 相应 的 变量 值 解 
析 方 法 等 属性 也 设置 好 。 























5.2) 通常 变量 名 是 非常 明确 的 ， 可 以 在 C 代 码 中 定义 变量 时 用 hard code 的 方式 编写 变量 
名 ， 然 而 还 有 一 些 变量 具有 两 个 特点 : 它们 的 名 称 是 未 知 的 ， 但 是 如 何 解析 它们 却 是 一 目 了 
然 的 。 例 如 ，HTTP 的 URL 中 的 变量 ， 就 像 请 求 /sitemap.xmlpage_num=2 里 的 page_ num， 如 何 
解析 它 是 非常 明确 的 ， 就 是 在 HTTP 请 求 行 ? 符号 后 的 参数 中 按 规则 解析 出 page_num 即 可 。 
这 样 的 参数 五 花 八 门 ， 什 么 样 的 都 有 ， 解 析 方 法 实际 只 有 一 个 : 根据 变量 名 在 一 段 字 符 串 中 
找到 即 可 。 这 样 的 请 求 Nginx 总 结 为 5 类 ， 它 们 仅 需 要 5 个 固定 的 解析 变量 方法 即 可 ， 而 每 类 
中 的 变量 名 是 不 确定 的 ， 由 使 用 变量 的 模块 决定 。 这 5 类 变量 都 由 HTTP 框 架 定义 ， 而 要 求 使 
用 它们 的 模块 必须 在 变量 名 中 强制 定义 前 缀 为 http 、sent_ http 、upstream http 、cookie 或 者 
arg 。 这 5 类 变量 参见 表 15-1。 











表 15-1 5 类 特殊 HTITP 变 量 


NNn httpo://ww linuxorobe. con 








变量 前 组 意 义 解析 方法 
arg_ 请 求 的 URL 参数 ngx http_variable areument 
http 请 求 中 的 HITP 头 部 ngx http_variable unknown header in 
sent_ http 发 送 啊 应 中 的 HITP 头 部 ngx http variable unknown header out 
cookie Cookie 头 部 中 的 某 个 项 ngx http_variable cookie 
upstream http_ 后 冲服 务 侣 HITP 啊 应 头 部 ngx http upstream header variable 








5.3) 定义 变量 的 模块 是 希望 变量 可 以 被 快速 访问 的 ， 然 而 ， 它 不 能 寄 希 望 于 变量 被 索 
引 ， 因 为 是 否 索引 是 使 用 变量 模块 的 权力 ! 于 是 定义 的 变量 就 需要 被 hash 为 散 列 表 来 加 速 访 
问 。 另 一 个 问题 是 5.2 步 的 5 类 名 字 不 明确 的 HTTP 变 量 怎么 办 ?只 有 使 用 变量 的 模块 才 知 道 
明确 的 变量 名 ， 定 义 它们 的 ngx_http_core_module 模 块 不 知道 变量 名 就 无 法 按照 变量 名 hash 成 
散 列 表 。 所 以 这 一 步 构造 散 列表 ， 将 除 表 15-1 的 5 类 变量 以 外 的 、 没 有 显 式 设置 不 要 hash〈 参 
见 15.2.2 市 ) 的 变量 生成 到 一 个 静态 的 开 散 列表 中 。 








下 面 在 了 解 变量 的 工作 机 制 之 前 ， 还 要 先 介绍 相关 的 结构 体 。 


15.2.2 ”相关 数据 结构 详 述 











变量 由 变量 名 和 变量 值 组 成 。 对 于 同一 个 变量 名 ， 随 着 场景 的 不 同 会 具有 多 个 不 同 的 
值 ， 如 果 认 为 变量 值 和 变量 名 一 一 对 应 从 而 使 用 一 个 结构 体 表 示 ， 毫 无 疑问 会 有 大 量 内 存 浪 
费 在 相同 的 变量 名 的 存储 上 。 因 此 ，Nginx 中 有 一 个 保存 变量 名 的 结构 体 ， 叫 做 
ngx_http_variable t， 它 负责 指定 一 个 变量 名 字符 串 ， 以 及 如 何 去 解 析出 相应 的 变量 值 。 所 有 
的 变量 名 定义 ngx_http_variable_t 都 会 保存 在 全 局 唯一 的 ngx_http_core_main conf {对 象 中 ， 解 
析 变 量 时 也 是 围绕 着 它 进行 。 














存储 变量 值 的 结构 体 叫 做 ngx_http_variable_ value t。 它 既 有 可 能 是 在 读 取 变量 值 时 被 创 
建 出 来 ， 也 有 可 能 是 在 初始 化 一 个 HITP 请 求 时 就 预 创 建 在 ngx_http request t 对 象 中 ， 这 将 视 
描述 变量 名 的 ngx_http_variable t 结 构 体 成 员 而 定 。 





1. 变 量 的 定义 ngx http variable t 
口 由 掉 岂 有 由 和 所 所 http' /wNv inuxorobe. con 





我 们 先 来 看 看 ngx_ http_variable t 的 结构 : 


struct ngx http variable s { 


// name 就 


nginx.conf 中 常 


是 字符 串 变 量 名 ， 例 如 


见 的 


$remote addr 这 样 的 字符 串 ， 


// 当然 ， 


$ 符 号 是 不 包括 的 


ngx str t name; 
// 如 果 需 要 变量 最 初 赋值 时 就 进行 变量 值 的 设置 ， 那么 可 以 实现 


set handler 方 


法 。 如 果 我 们 定义 的 


// 内 部 变量 允许 在 


nginx.conf 中 以 


set 方 式 又 重新 设置 其 值 ， 那 么 可 以 实现 该 方法 (参考 





args 参 数 ， 


// 它 就 是 一 个 内 部 变量 ， 同 时 也 允许 


set 方 式 在 





nginx.Con 开 里 必 


15.4 节 


新 设置 其 值 ) ， 详 见 


ngx http set Variable pt set handler; 
// 每 次 获取 一 个 变量 的 值 时 ， 会 先 调用 


get handler 方 法 ， 所 以 


Nginx 的 官方 模块 变量 的 解析 大 都 


// 在 此 方法 中 完成 


ngx http get variable pt et handler; 
“ 必 直 直下 导 下 下 半生 如 站 








htt po: // WW | 1 NuUxpor obe. con 


get handler、 


set handler 回 调 方法 使 用 


uintptr t data; 
// 变量 的 特性 ， 下 文 详 述 


ngx uint 七 flags; 


// 这 个 数字 也 就 是 变量 值 在 请 求 中 的 缓存 数组 中 的 索引 


ngx uint 七 index; 
}; 
typedef struct ngx http variable s ngx http variable t; 








下 面 看 看 上 面 的 get_handler 和 set_handler 对 应 的 方法 类 型 ngx_http_set_variable_pt 是 怎样 
的 ， 当 本 章 后 续 定 义 新 的 和 目 有 变量 时 ， 就 必须 要 实现 相应 的 解析 变量 值 的 方法 : 





typedef void (*ngx http set variable pt) (ngx http request t r, 
ngx http variable value t v, uintptr 七 data); 
typedef ngx int 七 (*ngx http get variable pt) (ngx http request t r,ngx http variable value t v, uintptr t data, 





可 以 看 到 ， 它 们 均 接 收 3 个 参数 ， 表 示 请 求 的 r， 表 示 变 量 值 的 v， 以 及 一 个 可 能 使 用 到 
的 参数 data， 这 个 data 也 就 是 定义 变量 名 的 ngx http variable t 结 构 体 中 的 data 成 员 。 这 两 个 解 
析 方 法 和 data 成 员 在 15.2.5 节 会 详细 说 明 。 











flags 成 员 是 一 个 整 型 ， 它 是 按 位 来 设计 的 ， 目 前 仅 有 前 4 位 设 定 了 含义 ， 所 以 共有 4 种 取 
值 的 组 合 ， 这 前 4 位 定义 如 下 所 示 : 








#define NGX HTTP VAR CHANGEABLE 
#define NGX HTTP VAR NOCACHEABLE 
#define NGX HTTP VAR INDEXE 
#define NGX HTTP VAR NOHASH 


























Pad 
口 














EM = 





每 个 flags 标 志 位 的 含义 见 表 15-2。 


表 15-2 HTTP 变量 名 ngx_http_vatiable ft 中 的 flags 标 志 位 意义 
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flags 标志 位 总 义 

表示 对 应 的 变量 值 可 以 改变 ， 也 就 是 对 一 个 请 求 内 的 同一 个 变量 可 以 
反复 se 其 变量 值 。 反 过 来 说 ， 如 果 没 有 这 个 标志 位 ， 一 旦 对 一 个 赋 
过 值 的 变量 重新 赋值 就 会 报错 。 对 于 内 部 变量 ,再 深入 看 看 可 以 知道 ， 
没有 这 个 标志 位 的 变量 ， 是 不 允许 一 次 以 上 定义 同一 变量 名 的 ， 因 为 多 


NGX HTTP VAR CHANGEABLE 局. a 
次 设置 变量 的 解析 方法 与 修改 变量 值 是 等 价 的 ， mdse 在 Nginx 启动 时 


发 现 错误 “ the duplicate…variable”， 就 是 这 个 原因 。 特 别 对 于 15.4 节 
介绍 的 外 部 变量 ， 它 们 一 定 允 许 反复 修改 同一 变 最 的 值 ， 所 以 必须 加 上 
该 标志 位 
( 续 ) 
flags 标志 位 意 义 


一 


不 要 缓存 这 个 变量 的 值 ， 每 次 使 用 变量 时 都 需要 重新 解析 。 为 什么 不 
人 
As 改变 ， 如 $uri 这 个 变量 ， 如 果 读 取 到 了 上 一 次 绥 存 的 值 是 无 法 确定 

是 和 下 正确 的 

将 本 | ， 加 速 访问 。 为 什么 又 要 缓存 一 些 变 量 的 值 呢 ? 因为 有 些 

上 量 在 一 次 请 求 的 执行 中 是 永远 不 变 的 ， 例 如 $request_uri 这 个 变量 ， 
地 自 客户 端的 请 求 URI， 自 然 不 会 变化 ， 那 么 绥 存 之 后 的 

复 使 用 速度 就 会 更 快 
不 要 把 这 个 变量 hash 到 散 列 表 中 。 为 什么 会 想 着 使 一 个 变量 不 做 散 列 
人 改 列 表 也 是 需要 消耗 内 存 的 ， 如 果菜 个 模块 设计 了 一 
NGX HTTP VAR NOHASH 个 可 选 变量 提供 给 其 他 模块 使 用 ， 并 且 要 求 如 果 有 其 他 模块 使 用 该 变量 
ee 须 索 引 化 下 使 用 ( 即 不 能 调用 ngx_http_get_variable 方法 来 获取 变 
量 值 )， 这 样 ， 这 个 变量 就 不 用 浪费 散 列 表 的 存储 空间 了 


NGX HTTP VAR NOCACHEABLE 


NGX HTTP VAR INDEXED 


© 提示 Nginx 中 有 一 个 “Embedded Variables” 概 念 ， 例 如 negx_http_fastcgi_module、 

ngx_http_gzip_module 等 模块 都 提供 了 这 样 的 “ 谱 入 式 变量 ”。 其 实 ， 这 种 变量 就 是 指 本 模块 
提供 了 可 选 变量 仅 供 其 他 模块 〈 而 不 是 更 改 hginx.conf 配 置 文件 的 用 户 ) 使 用 ， 而 其 他 模块 使 
用 时 也 只 能 先 把 变量 索引 化 再 使 用 ， 不 能 依据 散 列 表 使 用 变量 。 这 种 “内 入 式 变量 ”通常 就 
会 指定 flags 中 含有 NGX_HTIP_VAR_NOHASH 标 志 。 这 里 有 两 点 需要 注意 : 中 变量 是 可 选 
的 ， 也 就 是 说 ， 使 用 了 该 模块 的 其 他 Nginx 模 块 不 用 这 个 变量 一 样 可 以 工作 ， 所 以 这 个 变量 
不 应 当 占 用 散 列 表 ; (名 若 其 他 模块 使 用 该 变量 ， 则 必须 先 通过 ngx_http_get_variable_index 方 
法 把 变量 索引 化 ， 才 能 获取 变量 值 。 


2. 变 量 值 ngx http variable value t 
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描述 变量 值 的 结构 为 ngx http variable value t， 实 际 上 等 价 于 ngx variable value t: 





typedef ngx variable value t ngx http variable value 七 ; 








看 看 它 包 括 哪些 成 员 : 





typedef struct { 
// 变量 值 必须 是 在 一 段 连续 内 存 中 的 字符 串 ， 值 的 长 度 就 是 


len 成 员 


unsigned len:28; 
// valid 为 


1 时 表示 当前 这 个 变量 值 已 经 解析 过 ， 且 数据 是 可 用 的 


unsigned valid:1; 
// no_cacheable 为 


1 时 表示 变量 值 不 可 以 被 缓存 ， 它 与 


ngx http _ variable 鞋 结构 体 


flags 成 员 


// 里 的 


NGX HTTP VAR NOCACHEABLE 标 志 位 是 相关 的 ， 即 设置 这 个 标志 位 后 





no _cacheable 就 会 为 


下 
unsigned no_ cacheable:1; 
// not found 为 
1 表示 当前 这 个 变量 值 已 经 解析 过 ， 但 没有 解析 到 相应 的 值 


unsigned not found:1; 


// 仅 由 


ngx_http 1og moqule 模 块 使 用 ， 用 于 日 志 格 式 的 字符 转 义 ， 其 他 模块 通常 忽略 这 个 字段 


unsigned escape:1; 


// data 就 指向 变量 值 所 在 内 存 的 起 始 地 址 ， 与 


口 由 掉 岂 有 所有 和 所 http' /wNv inuxorobe. con 





1Len 成 员 配合 使 用 


u Shar *data; 
} ngx variable value t; 








3. 存 储 变 量 名 的 数据 结构 


HTTP 框 架 的 核心 结构 体 ngx http core main conf t 中 有 3 个 成 员 与 HTTP 变 量 是 相关 的 ， 
如 下 所 示 : 





typedef struct { 
// 存储 变量 名 的 散 列 表 ， 调 用 


ngx_http get variable 方法 获取 未 索引 的 变量 值 时 就 靠 这 个 


// 散 列 表 找 到 变量 的 解析 方法 


ngx hash 七 Variables hash; 


// 存储 索引 过 的 变量 的 数组 ， 通 常 各 模块 使 用 变量 时 都 会 在 


Nginx 启 动 阶段 从 该 数组 中 获得 索引 号 ， 


// 这 样 ， 在 


Nginx 运 行 期 内 ， 如 果 变 量 值 没有 被 缓存 ， 就 会 通过 索引 号 在 


variables 数 组 中 找到 


// 变量 的 定义 ， 再 解析 出 变量 值 


ngx array 七 variables; 


// 用 于 构造 


variables hash 散 列表 的 初始 结构 体 


ngx hash keys arrays 七 *variables keys; 
} ngx http core main conf t; 














这 3 个 成 员 中 ，variables_ hash、variables 会 在 Nginx 的 正常 运行 中 使 用 ， 而 variables keys 


oo 人 让 站 站 用 计 伯 各 jalean Ts EE 0 





功 生 成 后 variables_keys 就 功 成 身 退 了 。 


4. 绥 存 变量 值 的 数据 结构 





变量 值 如 果 可 以 被 缓存 ， 那 么 它 一 定 只 能 绥 存 在 每 一 个 HTTP 请 求 内 ， 对 于 Nginx 这 样 一 
个 Web 服 务 器 来 说 ， 不 可 能 为 不 同 的 HTTP 请 求 缓存 同一 个 值 。 因 此 绥 存 的 变量 值 就 在 表述 
一 个 HTTP 请 求 的 ngx_http_request t 结 构 体 中 ， 如 下 : 











struct ngx http request s { 
// variables 数 组 存储 所 有 序列 化 了 的 变量 值 ， 数 组 下 标 即 为 索引 号 


ngx http _ variable value 七 *variables; 


} 





当 HTTP 请 求 刚 到 达 Nginx 时 ， 就 会 创建 缓存 变量 值 的 variables 数 组 ， 如 下 : 





ngx http request 七 * 
ngx http create request (ngx connection 七 C) 
{ 
ngx http request t r; 
ngx http core main conf 七 *cmcf; 
cmcf = ngx http get module main conf(r, ngx http core module); 
// 缓存 变量 值 的 








Variables 数 组 下 标 ， 与 索引 化 的 、 表 示 变 量 名 的 数组 


cmcf->variables 下 标 ， 


// 它们 是 一 一 对 应 的 


r->variables = ngx pcalloc(r->pool, cmcf->variables.nelts * sizeof (ngx http variable value t)); 


} 





一 旦 某 个 变量 的 ngx http variable value {t 值 结构 体 被 缓存 ， 取 值 时 融会 优先 使 用 它 。 


5. 内 存 布 局 





了 解 了 相应 的 结构 体 后， 我 们 可 以 从 它们 在 Nginx 内 存 中 如 何 布局 入 手 ， 掌 握 其 用 法 。 
TiNiNnnn http://wWwWw linuxorobe.con 





欲 了 解 其 内 存 布局 ， 当 然 首先 从 ngx_http core main conf t 中 的 3 个 成 员 来 串 起 各 结构 
体 。variables_keys 仅 用 于 构造 variables_hash 散 列表 ， 它 也 是 Nginx 构 造 散 列表 的 必 经 步 又 ， 
读者 朋友 可 以 参考 第 7 章 ， 这 里 不 再 介绍 。 我 们 重点 看 看 variables_hash 散 列表 中 的 变量 与 
variables 索 引 数 组 中 的 变量 有 何 关 联 ， 参 见 图 15-2。 
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ngx_hash_elt 


len 
自问 
EE RE PE EE [生生 生生 到 
开 散 列表 


ngx_http_core_main_conf t 


variables_hash 


variables_keys 


varlables 


| 





flags 同 时 满足 二 者 的 同名 变量 ，flags 外 的 参数 必须 完全 一 致 


索引 0 索引 1] 索引 2 索引 3 索引 4 
FE EE PO EE 
CC 


NS pape 
n gx_http_variabte_t 构 成 的 数组 
\ RN 


\ ngx_http_variable_t 


| 
. 
、 |flags ( 含 NGX_HTTP_VAR_INDEXED ) 


\ 





图 15-2 ”定义 变量 的 ngx_http_variable_t 结 构 体 在 内 存 中 的 布局 
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可 以 看 到 ， 散 列表 与 索引 数组 中 都 存放 着 各 自 的 ngx_http_variable _t 结 构 体 ， 即 使 name 相 
同 的 同一 个 变量 ， 如 果 既 被 索引 又 被 hnash 的 话 ， 仍 然 会 有 两 份 ngx_http_variable t 结 构 体 ， 除 
了 flags 成 员 会 有 不 同 外 ， 它 们 的 其 他 成 员 都 是 相等 的 。 使 其 各 成 员 “ 相 等 ”这个 操作 是 在 图 15- 
1 的 第 5.1 步 又 的 ngx http variables init vars 方 法 完成 的 ， 感 兴趣 的 朋友 可 以 阅读 源 代码 。 








这 里 的 含义 就 是 ， 同 一 个 变量 名 称 可 以 同时 既 被 索引 又 被 hpash， 但 一 定 只 有 一 种 解析 变 
量 的 方法 ， 所 以 ， 同 一 变量 可 以 同时 拥有 两 个 ngx http variable t 结 构 体 。 








无 论 是 索引 还 是 hash， 都 必须 针对 明确 的 变量 名 。 可 是 在 表 15-1 中 却 有 5 类 特殊 变量 ， 它 
们 只 是 前 级 固定 为 http 、sent http 、upstream http 、cookie 或 者 are ， 唯 有 在 模块 使 用 1 个 
具体 的 变量 时 才能 确定 完整 的 变量 名 称 。 确 定 了 完整 名 称 的 特殊 变量 是 可 以 被 索引 的 ， 却 不 
应 该 被 hash 到 散 列 表 中 ， 为 什么 呢 ? 因为 进入 散 列 表 的 变量 都 是 由 模块 重 定义 解析 方法 的 ， 
而 这 5 类 特殊 变量 则 可 以 复 用 HTTP 框 架 已 经 准备 好 的 通用 解析 方法 。 所 以 索引 变量 、 散 列表 
变量 、 特 殊 变 量 会 组 合 为 5 种 关系 ， 如 图 15-3 所 示 。 
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variables_hash 存 放 的 hash 过 的 变量 


同时 被 hash 和 有 索 


引 的 变量 


variables 存 放 的 索引 过 的 变量 


被 索引 的 特殊 变量 


5 类 特殊 变量 





图 15-3 ”索引 变量 、hash 变 量 、 特 殊 变 量 间 的 集合 关系 
图 15-3 中 有 4 个 要 点 : 
1) 同一 个 变量 可 以 同时 被 hash 和 索引 。 


2) 变量 并 非 要 么 在 散 列 表 中 ， 要 么 在 索引 数组 中 。 对 于 特殊 变量 ， 是 可 以 绕 开 二 者 用 
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ngx_http get_variable 方 法 获取 其 值 的 。 





3) 对 于 特殊 变量 ， 是 可 以 使 用 索引 的 方式 来 获取 其 值 的 ， 这 也 是 最 第 用 的 方式 。 











4) 不 要 重 定义 特殊 变量 ， 重 定义 的 特殊 变量 可 能 存在 于 散 列 表 中 〈 未 设置 
NGX HTTP VAR NOHASH 标 志 位 ) 。 





下 面 我 们 通过 图 15-4 来 看 看 索 引 过 的 变量 在 内 存 中 是 怎么 使 用 的 。 








变量 的 索引 由 两 部 分 组 成 ， 一 是 定义 变量 的 ngx_http_variable 结构 体 构成 的 索引 数组 ; 
二 是 描述 变量 值 的 ngx_http_variable_value_t 结 构 体 构成 的 数组 。 前 者 在 Nginx 只 有 全 局 的 唯一 
一 份 ， 存 储 在 ngx_http_core_main_conf t 绍 构 体 的 variables 中 ; 后 者 对 每 一 个 HTTP 请 求 都 会 有 
一 份 ， 存 储 在 ngx_http_request t 结 构 体 的 variables 中 。 这 两 者 间 同 属于 一 个 变量 的 名 字 、 值 在 
各 目 数 组 中 的 索引 号 都 是 一 一 对 应 的 。 











想 以 索引 方式 使 用 变量 的 模块 ， 都 会 在 模块 初始 化 阶段 获得 索引 号 ， 在 Nginx 运 行 中 、 
HTTP 请 求 到 达 时 ， 则 会 根据 这 个 索引 号 ， 要 么 从 ngx_http_variable {构成 的 数组 中 找到 变量 
定义 并 使 用 get_ handler 方 法 解析 出 变量 值 “如 果 flags 参 数 指明 可 以 缓存 ， 那 么 还 会 缓存 到 请 
求 中 ) ， 要 么 从 ngx_http_variable_value t 构 成 的 数组 中 直接 获得 缓存 的 变量 值 。 
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这 个 数组 主要 用 于 存 
放 所 有 被 索引 过 的 变 
量 定义 ， 特 别 是 其 解 
析出 变量 值 的 方法 


ngx_http_core_main_conf_t+ 


variables_keys 
variables_hash 















索引 0 索引 1 索引 2 索引 3 索引 4 


ngx_http_variable_t 构成 的 数组 |/ 
pg 















x / 
7 / 
/ 时 
,。 解析 值 
/ 
7/ 使 用 变量 的 模块 
index==4 i el 
get_handler 解 析 值 用 index 索 引号 ==4 


设置 值 获得 缓存 值 


ngx_http_request_t 











索引 0 ; 索引 1 : 索引 2 : 索引 3 : 索引 4 











ngx_http_request_t 








eee ingx_http_variable_value_t 用 于 缓存 变 
oe 量 什 各 丰 
[| 请 求 都 有 该 






数组 


ngx_http_variable_value_t / 


en 
oa, 指向 变量 值 ”|，/ 
Tttpf/ WW inuxorobe. con 








图 15-4 索引 过 的 变量 内 存 使 用 示意 图 





每 一 个 HITP 请 求 都 必须 为 所 有 缓存 的 变量 建立 ngx_http_variable_value 堵 组 ， 这 似乎 有 
些 内 存 浪 费 ， 因 此 ， 不 使 用 索引 而 是 散 列 表 来 使 用 变量 也 是 可 以 的 ， 此 时 其 内 存 布局 如 图 
15-$5 所 示 。 
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ngx_http_core_main_conf ft 


ngx_hash_elt_t 











variables 





variables_keys 





variables_hash 











nr 
开 散 列表 


使 用 变量 的 模块 











根据 hashkey 和 name 查 询 散 列表 





ngx_http_variable_t 











索引 过 的 变量 会 先 取 缓存 值 


A 


索引 2 | 








ngx_http_request_t 


variables 












: 未 索 引 室 车 则 构造 新 的 ngx_ http_variable_value_t 
索引 3 ; 索引 4 








ws | 索引 1 : 


ngx_http_variable_value_t 


len， 变 量 值 的 长 度 
data， 指 癌变 量 值 





















ngx_http_variable_value_t 





len， 变 量 值 的 长 度 
data， 指 癌变 量 值 
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图 15-5 散 列 过 的 变量 内 存 使 用 示意 图 


此 时 ， 使 用 变量 的 模块 不 用 在 Nginx 初 始 化 阶段 做 些 什么 ， 只 要 这 个 变量 已 经 有 模块 定 

义 过 ， 那 么 在 处 理 请 求 时 ， 仅 需 要 把 变量 名 字符 串 按照 hash 方 法 求 出 散 列 值 ， 就 可 以 在 
ngx http core main conf t 结 构 体 的 variables_hash 散 列表 中 找到 定义 变量 的 ngx http variable t 
结构 体 ， 如 果 其 flags 成 员 指明 变量 是 被 索引 的 ， 那 么 会 根据 index 成 员 直 接 向 请 求 的 variables 
数组 里 获得 预 分 配 的 ngx http_variable_ value t 绪 构 体 ， 这 个 变量 值 知 没 有 解析 过 ， 束 会 用 该 

结构 体 传 给 get_ handler 方 法 解析 、 绥 存 〈 如 果 可 以 的 话 ) 。 如 果 flags 成 员 没 有 说 明 变量 被 索 
引 过 ， 那 么 就 会 在 请 求 的 内 存 池 里 新 分 配 1 个 ngx_http_variable_value 结构 体 ， 用 于 传递 给 
get_handler 方 法 解析 、 承 载 变量 值 。 











15.2.3 ”定义 变量 的 方法 


定义 新 的 内 部 变量 时 ， 通 过 ngx http add variable 方 法 进行 ， 其 定义 如 下 : 





ngx http variable t 
ngx http aaa variable (ngx conf t cf, ngx str t *name, ngx uint t flags); 





在 15.2.1 节 已 经 介绍 过 ， 添 加 变量 必须 是 在 preconfiguration 回 调 方法 中 ， 第 1 个 参数 cf 直 
接 把 preconfiguration 中 的 ngx_conf t 指 针 传 入 即 可 ，cf 的 用 途 有 两 个 : 定义 新 变量 一 定 会 放 到 
全 局 唯一 的 ngx_http_core_main_conf t 结 构 体 ， 参 数 cf 可 以 找到 这 个 全 局 配置 结构 体 ， 分 配 变 
量 相 关 结 构 体 的 内 存 时 ， 可 以 用 cf 的 内 存 池 。 第 2 个 参数 就 是 变量 的 名 称 。 第 3 个 参数 等 价 于 
ngx http variable t 中 的 flags 成 员 。 








返回 值 就 是 已 经 准备 好 的 、 用 于 定义 变量 的 ngx_http_variable t 结 构 体 。 此 时 ， 这 个 结构 
体 的 name 和 flags 成 员 已 经 设置 好 了 ， 这 时 需要 定义 变量 模块 做 的 工作 就 是 指定 解析 方法 ， 包 
括 指定 get handler、set_ handler 〈 很 少 设置 ) 、data (如 果 有 必要 的 话 ) 。 在 15.2.5 节 中 再 来 
介绍 如 何 实现 解析 方法 。 
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@ 注 症 ”如 果 这 个 交 量 曾经 被 其 他 模块 添加 过 ， 那 么 此 时 的 返回 值 ngx_http_variable_t 
就 是 其 他 模块 已 经 设置 过 的 对 象 ， 它 的 get_handletr 等 成 员 可 能 已 经 设置 过 了 。 开 发 模块 新 变 
量 时 应 当 妥 善 处 理 这 种 变量 名 冲突 问题 。 


15.2.4 ”使 用 变量 的 方法 


使 用 变量 时 会 使 用 表 15-3 中 所 列 的 4 个 方法 。 














使 用 变量 时 有 两 种 方式 : 第 一 种 方式 是 索引 变量 ， 表 15-3 的 前 3 个 方法 都 只 用 于 索引 变 
量 ， 有 索引 变 量 效率 更 高 〈 且 可 以 被 缓存 ) ， 但 可 能 会 消耗 稍 多 点 的 内 存 ; 第 二 种 方式 是 非 索 
引 的 、hash 过 的 变量 ，ngx http get variable 方法 用 于 此 目的 。 














@ 注意 如果 这 个 变量 被 索引 过 ， 那 么 npgx_http_pet_vatiable 方 法 会 优先 在 
ngx_http_tfequest_t 中 缓存 变量 值 的 vatiables 数 组 中 的 获取 值 。 是 否 被 索引 过 的 依据 就 是 检查 


flapgs 参 数 是 否 含 有 NGX_HTTP VAR_INDEXED 标 志 位 。 


表 15-3 ”获取 HTTP 变 量 值 的 3 个 方法 
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方法 名 意 义 
设置 变量 被 索引 ， 并 获得 索引 号 ， 它 是 使 用 ngx_http_get_indexed_variable、 
ngx _http_get flushed variable 方法 的 前 置 方法 . 
调用 它 意味 着 这 个 变量 会 被 频繁 地 使 用 ， 和 希望 Nginx 处 理 这 个 变量 时 效率 更 


高 ， 体 现在 : 
ngx http get variable index e 变量 值 可 以 被 缓存 ， 重 复读 取 时 不 用 -~ 次 解析 
e 定义 变量 的 解析 方法 时 ， 可 以 通过 索引 直接 找到 该 方法 进行 解析 ， 而 不 是 
通过 操作 获 列 表 


e Neginx 初始 化 HITP 请 求 时 ， 就 需要 为 这 个 变量 预 分 配 ngx_http_variable_ 

value t 变量 值 结构 体 

根据 ngx_http get variable index 得 到 的 索引 号 ， 获 取 被 索引 过 的 变量 的 
值 。 若 变量 被 解析 过 一 次 后 其 值 是 会 被 缓存 的 ， 这 样 该 方法 再 次 调用 后 将 会 
直接 获取 缓存 过 的 值 ， 而 不 是 重新 解析 。 这 个 方法 是 忽略 NGX_HTTP VAR_ 
NOCACHEABLE 标志 位 的 

与 ngx_http_get indexed_ variable 相似 ， 区 别 是 : 如果 flags 中 设置 了 NGX 
HTTP VAR NOCACHEABLE 标志 人 位， 那么 ngx http get indexed Variable 方 
法 会 忽略 这 个 标志 位 ， 本 方法 则 会 不 使 用 已 经 缓存 的 变量 值 ， 每 次 取 值 时 皆 重 


ngx http get indexed variable 


ngx http get flushed variable 


新 解析 
根据 变量 名 称 ， 生 hash 过 的 散 列 表 里 找到 相应 的 变量 并 调用 其 解析 方法 
nex http get Variable 获得 值 ， 这 里 不 存在 缓存 变量 值 的 可 能 。 同 时 和 若 变 量 是 属于 表 15-1 里 的 5 种 


特殊 变量 ， 也 可 以 从 坟 为 法 中 获取 解析 出 的 值 


15.2.5 ”如 何 解 析 变 量 


首先 回顾 一 下 解析 变量 的 主要 方法 get_handler 的 方法 原型 : 





typedef ngx int 七 (*ngx http get variable pt) (ngx http request t r,ngx http variable value t v, uintptr t data, 








参数 r 和 data 剖 用 来 帮助 生成 变量 值 ， 而 v 则 是 存放 值 的 载体 。 结 构 体 v 已 经 分 配 好 内 存 了 
《调用 get handler 的 函数 负责 ) ， 当 然 分 配 好 的 内 存 中 是 不 包括 字符 串 变 量 值 的 。 可 以 使 用 
请 求 1 的 内 存 池 来 分 配 新 的 内 存放 置 变量 值 ， 这 样 请 求 结束 时 变量 值 就 会 锌 释放， 可 见 变 量 
值 的 生命 周期 与 请 求 是 一 致 的 ， 而 变量 名 则 不 然 。 将 参数 v 的 data 和 len 成 员 指 癌变 量 值 字符 
捉 即 完成 了 变量 的 解析 。 这 一 过 程 本 来 共性 特征 并 不 多 ， 然 而 vintptr_t data 参 数 却 有 一 些 通 
用 的 “玩法 ”， 本 市 则 简要 介绍 一 下 : 
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(1) uintptr_ t data 参 数 不 起 作用 


如 果 只 是 生成 一 些 和 用 户 请 求 无 关 的 变量 值 ， 例 如 当前 时 间 、 系 统 负载 、 磁 盘 状 况 等 ， 
那么 这 与 读者 朋友 的 需求 有 关 ， 使 用 各 种 手法 获得 变量 值 后 赋 给 参数 v 的 data 和 len 成 员 即 
可 。 或 者 说 ，ngx_http request_ ttr 中 的 成 员 已 经 足够 解析 出 变量 值 了 ，data 参 数 不 用 也 罢 。 举 
个 例子 ，HTTP 框 架 提供 了 一 个 变量 一 一 body bytes_sent， 表 示 一 个 请 求 的 响应 包 体 长 度 ， 常 
用 在 access.log 访 问 日 志 中 ， 它 的 解析 方法 设置 为 ngx_http_variable_ body _ bytes_sent，uintptr t 
data 因 为 不 使 用 则 设 为 0， 如 下 所 示 : 














static ngx http variable t ngx http core variables[] = { 
{ngx string("body bytes sent"),NULL, 
ngx http variable body bytes sent, 

0, 0, 0 1}, 





} 





而 ngx_http_variable_body_bytes_sent 解 析 啊 应 包 体 长 度 变 量 的 值 时 仅 从 请 求 r 中 就 获取 到 
足够 信息 了 ， 如 下 : 





static ngx int 七 

ngx http variable body bytes sent (ngx http request 七 r, 
ngx http variable value t v, uintptr t data) 

{ 
避让 二 “七 sent; 
// 发 送 的 总 响应 值 减 去 响应 头 部 即 可 


sent = r->connection->sent - r->header size; 





(2) uintptr t data 参 数 作为 指针 使 用 


uintptr_t 是 一 个 可 以 放置 指针 的 整 型 ， 所 以 ，uintptr_t data 就 被 设计 为 既 用 来 做 整 型 偏 移 
值 ， 又 用 来 做 指针 。 下 面 看 看 HTTP 框 架 把 data 用 来 做 指针 的 一 个 例子 ， 我 们 知道 有 5 类 特殊 
变量 ， 它 们 以 特殊 的 字符 串 打 头 ， 例 如 http_ 或 者 sent_http ， 实 际 上 每 一 个 这 样 的 变量 其 解析 
方法 都 大 同 小 异 ， 遍 历 解 析出 来 的 r->headers in.headers 或 者 r->headers in.headers 数 组 ， 找 到 
变量 名 再 返回 其 值 即 可 。 那 么 怎样 设计 通用 的 解析 方法 呢 ? 答案 就 是 把 uintptr_t data 作 为 指 
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针 指 向 实际 的 变量 名 字符 串 。 如 下 所 示 ， 当 出 现 了 如 http 这 样 的 变量 被 模块 使 用 时 ， 就 把 
data 作 为 指针 来 保存 实际 的 变量 名 字符 串 v[i].name (ngx http variables init vars 初 始 化 特殊 变 
量 时 的 代码 段 ) 。 








if (ngx strncmp(v[i] .name.data, "http ", 5) == 0) { 
v[il.get handler = ngx http variable unknown header in; 
v[il.dqata = (uintptr t) &v[il] .name; 


} 








而 解析 变量 的 get handler 方 法 再 把 data 转 为 ngx str t 字 符 串 变量 名 即 可 ， 如 下 : 





static ngx int 七 
ngx _ http variable unknown header in(ngx http request t r, 
ngx http variable value t v, uintptr t data) 





return ngx http variable unknown headerl(v, (ngx str t *) data, &r->headers in.headers.part, sizeof ("http ") 


} 








ngx_http_variable unknown header 方 法 就 只 是 裔 历 ngx_list 链表 类 型 的 headers 数 组 ， 找 到 
符合 变量 名 的 头 部 后 ， 将 其 值 作为 变量 值 返回 即 可 。 





(3) uintptr_t data 参 数 作为 序列 化 内 存 的 相对 偏 移 量 使 用 





很 多 时 候 ， 变 量 值 很 有 可 能 就 是 原始 的 HTTP 字 符 流 中 的 一 部 分 连续 字符 串 ， 如 果 能 够 
复 用 ， 束 不 用 为 变量 的 字符 串 值 再 次 分 配 、 找 贝 内 存 了 。 男 外 各 HTTP 模 块 在 使 用 get_handler 
解析 变量 时 ，HTTP 框 架 可 能 在 请 求 的 自动 解析 过 程 中 已经 得 到 了 需要 的 变量 值 ， 这 部 分 计 
算 工作 也 可 以 不 用 再 做 一 裔 。 那 么 能 不 能 据 此 两 点 加 快 解析 速度 呢 ?”data 参 数 作为 整 型 设计 
的 目的 就 在 于 此 。 





HTTP 框 架 中 会 解析 很 多 请 求 的 头 部 ， 如 http host、http_user agent 等 ， 它 们 实际 上 已 经 在 
请 求 头 部 接收 完整 时 就 已 经 解析 完了 ， 如 果 某 个 Nginx 模 块 需要 使 用 这 个 变量 ， 完 全 可 以 复 
用 ， 能 够 复 用 的 依据 在 于 : HTTP 框 架 解析 后 的 变量 值 ， 其 定义 成 员 在 ngx_http_request t 结 构 
体 里 的 位 置 是 固定 不 变 的 。 这 样 就 可 以 用 data 承 载 偏 移 量 直接 把 ngx_http_variable_value t 里 的 
data、len 指 向 变量 值 字符 串 即 可 。 例 如 主机 名 变量 http_host 其 实 正 对 应 着 ngx_http_request t 绪 
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构 体 里 的 headers in 成 员 的 host 成 员 ， 而 访问 浏览 器 http user_ agent 变 量 则 对 应 着 
ngx_http request t 结 构 体 里 的 user_agent 成 员 ， 它 们 的 解析 方法 都 是 专门 用 于 找 出 已 经 解析 过 
HTTP 头 部 的 变量 的 ngx http variable header 方 法 ， 而 data 则 是 偏 移 量 ， 如 下 : 





static ngx http variable t ngx http core variables[] = { 

{ ngx string("http host"), NULL, ngx http variable header, 
offsetof (ngx http request t, headers in.host), 0, 0 }, 

{ ngx string("http user agent"), NULL, ngx http variable header, 
offsetof (ngx http request t, headers in.user agent), 0, 0 }, 





} 





在 第 4 章 我 们 已 经 介绍 过 offsetof 方 法 ， 它 接收 两 个 参数 ， 并 认为 第 1 个 参数 是 一 个 struct 结 
构 体 ， 第 2 个 参数 是 其 成 员 ， 返 回 的 就 是 成 员 在 其 结构 体 中 的 偏 移 量 。 看 看 
ngx http variable _ header 方法 做 了 些 什么 








static ngx int 七 

ngx http variable header (ngx http request t *r, ngx http Variable Value t v, 
uintptr t data) 

{ 
ngx table elt t h; 
// data 偏 移 量 就 是 解析 过 的 


ngx table elt 七 类 型 的 成 员 ， 在 


ngx_http request 七 结构 体 中 的 偏 移 量 


i= (naxx table elt 让 (CS 人 着 data)y 
+ (hi) 
// 将 
len 和 
qata 指 向 字符 串 值 


V->len = Ph->value.lLlen'” 
Vv->valid = 1， 
Vv->no cacheable = 0; 
Vv->not found = 0; 
Vv->data = h->value.data; 
} else { 
v=>not found. = 1; 
} 
return NGX OK; 
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1$.3 ”定义 内 部 变量 





15.2 贡 已 经 完整 介绍 了 定义 内 部 变量 的 方法 ， 本 节 我 们 扩展 1$.1 节 的 例子 ， 定 义 新 的 内 
部 变量 供 其 他 模块 使 用 〈 就 像 嵌 入 式 变量 ， 即 本 模块 配置 项 是 不 支持 该 变量 的 ) ， 例 如 使 
ngx_http_ log_ module 模块 可 以 将 新 定义 的 变量 记录 到 access.log 访 问 日 志文 件 中 。 





我 们 定义 的 这 个 新 的 能 入 式 内 部 变量 叫做 i_chrome， 顾 名 思 义 ， 就 是 表示 这 个 请 求 是 否 
来 自 于 chrome 浏 览 姻 。 首 和 完 ， 要 在 源 代 码 中 定义 这 个 变量 名 称 ， 如 下 : 





static ngx str t new varaible is chome = ngx string("is chrome"); 





在 15.2.1 节 中 我 们 说 过 ， 必 须 在 preconfiguration 阶 段 定 义 变 量 ， 所 以 先 要 声明 一 个 在 
preconfiguration 阶 段 执行 的 方法 : 





static ngx int t ngx http mytest adqd variable (ngx conf t *cf); 








并 在 ngx_http module t 中 新 增 调用 ngx http mytest add variable 方 法 ， 如 下 : 








static ngx http module t ngx http testvariable module ctx = 











ngx http mytest add variable, /* preconfiguration */ 
ngx http mytest init, /* postconfiguration */ 
}; 
下 面 我 们 开始 实现 添加 变量 的 ngx_http_mytest add variable 


i 





me | 


ngx http mytest adqd variable 方 法 : 





static ngx int 七 


ngx http mytest add variable(ngx conf 七 *cf) { 








ngx http variable t *v; 
// 添加 变量 
V = ngx http aqq variable(cf, &new varaible is chome, NGX HTTP VAR CHANGEABLE); if (v == NULL) { 











return NGX ERROR; 





// 如 果 


is_chrome 这 个 变量 没有 被 添加 过 ， 那 么 


get handler 就 是 


NULL 空 指针 


Vv->get handler = ngx http ischrome variable; // 这 里 的 
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data 成 员 没 有 使 用 价值 ， 故 设 为 


return NGX OK; 





最 后 定义 is_chrome 变 量 的 解析 方法 : 





static ngx int t 


ngx http ischrome variable(ngx http request t *r, ngx http variable value t *v, uintptr t data) 


// 实际 上 


r->headers in.chrome 已 经 根据 


user agent 头 部 解析 过 请 求 是 否 来 自 于 


全 吧 


Chrome 浏 览 虽 


if (r->headers in.chrome) { 





xV = ngx http variable true value return NGX ORK; 
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xV = ngx http variable _ null value; return NGX OK; 





如 此 ，is_chrome 变 量 已 经 在 这 个 模块 中 添加 到 Nginx 中 了 ， 然 而 这 个 测试 模块 却 没有 相 
关 的 配置 项 直接 使 用 该 变量 。 所 以 只 有 其 他 使 用 到 该 变量 的 模块 才 可 能 提供 相应 的 配置 项 在 
nginx.conf 中 供 大 家 使 用 。 例 如 ，access_log 里 可 以 这 么 配置 : 





log format main "Sremote addr - [$time local] "$request" ' 


'$status S$body bytes sent "S$http referer™" ' 


'"$Shttp user agent" ischrome: $is chrome’ 




















这 样 束 会 记录 请 求 是 否 来 自 于 chrome。 其 实 这 个 变量 也 束 是 15.1 市 介绍 过 的 舱 入 式 变 


人 
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15.4 外 部 变量 与 脚本 引擎 


ngx_http_rewrite_module 模 块 使 用 了 Nginx 的 脚本 引擎 ， 提 供 了 外 部 变量 的 功能 。“ 外 部 变 
量 ” 与 前 几 节 介绍 的 变量 有 什么 不 同 呢 ? 这 里 的 定义 是 ， 变 量 名 称 是 在 nginx.conf 的 配置 文件 
里 声明 的 《不 像 在 C 源 代码 中 定义 的 内 部 变量 ) ， 且 在 配置 文件 里 确定 了 变量 的 赋值 。 





ngx_http_rewrite_module 模 块 定 义 的 外 部 变量 格式 为 : 
set S$variable value; 


这 一 行 配置 通过 set 关 键 字 定义 了 一 个 在 nginx.conf 中 指定 的 新 变量 variable， 并 将 其 赋值 
为 value。 这 个 value 是 一 个 文本 字符 串 ， 实 际 上 value 中 还 可 以 含有 多 个 变量 ， 也 可 以 是 变量 
与 文本 字符 串 的 组 合 。 这 种 外 部 变量 的 定义 非常 有 用 ， 尤 其 是 配合 rewrite 重 定 同 URL、ifEK 
键 字 等 ， 可 以 起 到 意 想不到 的 效果 ， 我 们 可 以 在 互联 网 上 找到 多 种 巧妙 的 用 法 ， 通 过 修改 
nginx.conf 融 得 到 了 丰富 的 功能 。 








很 多 程序 员 认 为 nginx.conf 的 设计 有 些 脚本 语言 的 味道 ， 因 为 它 可 以 定义 变量 、 可 以 跳 转 
到 不 同 的 程序 段 执行 、 拥 有 ifi 文 样 的 判断 型 配置 等 〈 当 然 这 些 都 是 ngx http_ rewrite module 模 
块 提供 的 ， 使 用 它们 必须 要 将 ngx_http rewrite module 模 块 编译 进 Nginx) 。 但 这 门 “ 脚 本 语 
言 " 却 有 些 独 特 的 味道 ， 与 编译 型 语言 相 比 ， 它 是 不 存在 预 编译 这 个 步骤 的 ， 只 有 Nginx 启 动 
过 程 中 才 会 把 脚本 式 配 置 项 载 入 Nginx 进 程 中 当然， 把 Nginx 的 局 动 理解 为 “编译 ” 步 又 的 
它 其 实 更 像 是 编译 语言 ) 。 与 解释 型 语言 相 比 ， 它 又 不 是 执行 到 某 一 行 脚 本 时 才 会 解释 
它 ， 而 是 Nginx 一 启动 就 会 检查 配置 项 的 合法 性 ， 并 把 所 有 的 脚本 式 语 句 都 “解释 ”为 C 程 序 ， 


车 
等 每 HTTP 请 求 到 来 时 执行 。 











md 
hh 





外 部 变量 虽然 在 Nginx 局 动 时 就 被 编译 为 C 代 码 ， 但 它们 是 在 请 求 处 理 过 程 中 才 被 执行 、 


生效 的 。 束 像 下 面 这 段 配 置 : 








location image { 
set imagewidth 100; 


location / { 


在 这 段 配置 里 ， 只 有 请 求 匹配 到 zaage 后 ， 外 部 变量 imagewidth 才 会 被 定义 并 被 赋值 为 
100《〈 或 者 imagewidth 已 经 被 定义 过 而 被 修改 值 为 100) ， 这 样 之 后 的 脚本 、 模 块 才 可 以 使 用 
imagewidth 变 量 。 反 之 ， 请 求 没 有 匹配 到 zage 就 不 会 执行 这 段 set 脚 本 。 


因此 ， 外 部 变量 的 设计 可 以 总 结 为 两 个 步 又 : 


1) Nginx 局 动 时 将 配置 文件 中 的 set 脚 本 式 配 置 编译 为 相关 的 数据 与 执行 方法 。 





2) 接收 到 HTTP 请 求 时 ， 在 NGX_HTTP_SERVER REWRITE PHASE 或 者 
NGX_HTTP_REWRITE_PHASE 阶 段 中 查找 由 配 了 的 location 下 是 否 有 待 执行 的 脚本 ， 如 果 有 
则 依次 执行 。 


本 节 并 不 会 完整 介绍 ngx http rewrite module 模 块 用 到 的 所 有 脚本 语法 ， 以 及 Nginx 脚 本 
引擎 的 完整 用 法 。 然 而 外 部 变量 已 经 足够 有 代表 性 了 ， 通 过 上 面 的 配置 作为 例子 介绍 其 工作 
原理 ， 读 者 朋友 就 可 以 清晰 地 了 解 到 脚本 引擎 的 用 法 ， 进 而 可 以 展开 阅读 
ngx_http_ rewrite module 模 块 源 代码 了 解 更 多 的 细节 。 














15.4.1 相关 数据 结构 


同一 段 脚本 被 编译 进 Nginx 中 ， 在 不 同 的 请 求 里 执行 时 效果 是 完全 不 同 的 ， 所 以 ， 每 一 
个 请 求 都 必须 有 其 独 有 的 脚本 执行 上 下 文 ， 或 者 称 为 脚本 引擎 ， 这 是 最 关键 的 数据 结构 。 在 
Nginx 中 ， 是 由 ngx http_script.h 文 件 里 定义 的 ngx_http_ script_engine t 结 构 体 充当 这 一 角色 ， 如 
下 所 示 : 


typedef struct { 
// 指向 待 执行 的 脚本 指令 
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u char 大 


// 变量 值 构成 的 栈 


ngx http _ variable value t *sp; 
// 脚本 引擎 执行 状态 


ngXx _ int status; 


// 指向 当 前 脚本 引擎 所 属 的 


HTTP 请 求 


ngx http request t *request; 


} ngx http script engine t; 











我 们 来 看 看 与 外 部 变量 相关 的 4 个 成 员 。 


ngx_http_variable_value_t*sp 是 一 个 栈 。 我 们 知道 任何 语言 都 需要 “ 栈 ” 这 样 一 个 数据 结构 
作为 编译 工具 ， 例 如 在 函数 的 调用 、 表 达 式 的 解析 时 。 对 set 定 义 的 外 部 变量 也 一 样 ， 它 需要 
sp 这 个 栈 来 存放 变量 值 。 栈 当然 也 有 大 小 ， 目 前 的 默认 大 小 为 10 个 变量 值 。 


request 很 简单 ， 指 向 了 HTTP 请 求 。 





u_char*ip 可 以 想象 为 卫 寄 存 器 ， 因 为 它们 的 目的 是 一 致 的 ， 都 是 指 癌 下 一 行将 要 执行 的 
代码 。 然 而 ip 却 是 一 个 u_char* 类 型 ， 它 指 癌 的 类 型 是 不 确定 的 。 它 指向 的 一 定 是 和 执行 的 肢 
本 指令 ， 难 道 没 有 规律 吗 ? 用 面向 对 象 的 语言 来 说 ， 它 指向 的 是 实现 了 
ngx_http_script_code_pt 接 口 的 类 。 当 然 C 语 言 里 没有 接口 、 类 的 概念 ， 在 C 语 言 里 要 想 实 现 上 

述 目的 ， 通 常会 用 馆 套 结构 体 的 方法 ， 比 如 表示 接口 的 结构 体 A， 要 放 在 表示 实现 接口 的 类 
结构 体 B 的 第 1 个 位 置 。 这 样 一 个 指 同 B 的 指针 ， 也 可 以 强制 转换 类 型 为 A 再 调用 A 的 成 
。 如 果 读 者 朋友 觉得 比较 抽象 ， 那 么 u_char*ip 指 问 ngx_http_script_code_pt 函 数 指针 束 是 一 
个 非常 好 的 例子 。 

















首先 ，ngx_http_script_code_pt 是 一 个 函数 指针 ， 当 然 它 即使 是 一 个 结构 体 也 无 所 谓 。 看 
看 它 的 定义 : 








typedef void (*ngx http Script code pt) (ngx http Script engine t xe) 











ngx_http_script_code_pt 的 唯一 参数 就 是 脚本 引擎 ngx_http_script_engine t， 它 表示 了 当前 
指令 的 脚本 上 下 文 。 


ngx_http_script_code_pt 相 当 于 抽象 基 类 的 一 个 接口 ， 所 以 会 有 相应 的 结构 体 担当 类 的 角 
色 。 对 于 “set" 配 置 来 说 ， 编 译 变量 名 〈 即 第 1 个 参数 ) 由 一 个 实现 了 ngx_http_script_code_pt 
接口 的 类 担当 ， 这 个 类 实际 上 是 由 结构 体 ngx http_script var_code t 来 承担 的 ， 如 下 所 示 : 








typedef struct { 
// 在 本 节 的 例子 中 ， 


code 指 向 的 脚本 指令 方法 为 


ngx http Script set var code 
ngx http script code pt code; 
// 表示 








ngx_http request 七 中 被 索引 、 缓 存 的 变量 值 数 组 


variables 中 ， 当 前 解析 的 、 


// set 设 置 的 外 部 变量 所 在 的 索引 号 


uintptr t index; 
} ngx http script Var code t; 








我 们 可 以 注意 到 ， 第 1 个 成 员 就 是 ngx http_script code ptcode， 这 意味 着 可 以 把 
ngx_http_script_var_code t 强 转 为 ngx_http_script_code_pt 方 法 执行 。 


看 到 了 uintptr_t 类 型 的 index 成 员 ， 大 家 可 能 又 会 想 ， 又 要 “多 用 途 ” 了 吗 ? 既 作 普通 整 型 
又 做 指针 ?这 里 纯粹 只 是 Nginx 的 习惯 而 已 ，index 成 员 只 用 来 做 表示 索引 号 的 整 型 ， 用 于 与 
ngx_http_request_t 请 求 中 索引 化 的 variables 变 量 值 配合 工作 。 这 里 我 们 已 经 看 到 ，set 定 义 的 
外 部 变量 只 能 作为 索引 变量 使 用 不 能 作为 hash 变 量 使 用 〉。 








set 的 第 2 个 参数 是 变量 值 ， 它 也 需要 一 个 新 的 结构 体 ngx_http_script_value_code t 来 编 
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译 ， 看 看 它 的 定义 : 





typedef struct { 
// 在 本 节 的 例子 中 ， 


code 指 向 的 脚本 指令 方法 为 


ngx http Script value _ code 
ngx http Script code pt code; 
// 若 外 部 变量 值 是 整数 ， 则 转 为 整 型 号 赋 给 








value， 否 则 


Value 为 


0 
uintptr t value; 


// 外 部 变量 值 ( 


set 的 第 


2 个 参数 ) 的 长 度 


uintptr t text len; 


// 外 部 变量 值 的 起 始 地 址 


uintptr t text data; 
} ngx http script value code t; 








对 于 ngx_http_script_code_p 人 方法 的 实现 我 们 在 15.4.3 节 再 解释 。 那 么 为 什么 一 行 set 脚 本 
要 分 别 由 编译 变量 名 、 编 译 变量 值 的 2 个 结构 体 来 表示 呢 ? 因 为 set 有 很 多 不 同 的 使 用 场景 ， 
对 变量 名 来 说 ， 就 存在 变量 名 首次 出 现 与 非 首次 出 现 ， 而 变量 值 就 有 纯 字 符 串 、 字 符 串 与 其 
他 变量 的 组 合 等 情况 。 把 变量 名 的 编译 提取 为 ngx_http_script_ var_code t 结 构 体 ， 使 所 有 变量 
名 的 编译 可 以 复 用 其 index 成 员 ， 而 具体 的 ngx_http_script code_ pt 指令 执行 则 可 以 各 自 实现 ; 




















把 变量 值 的 编译 提取 为 ngx http_script value_code tt 结构 体 则 可 以 复 用 text len、text data 成 


3 


ngx_http_script_engine_t 是 随 着 HTTP 请 求 到 来 时 才 创 建 的 ， 所 以 它 无 法 保存 Nginx 启 动 时 
就 编译 出 的 脚本 。 保 存 编译 后 的 脚本 这 个 工作 实际 上 是 由 ngx_http_rewrite_ loc_conf t 结 构 体 
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承担 的 ， 如 下 所 示 : 





typedef struct { 
// 保存 着 所 属 


location 下 的 所 有 编译 后 的 脚本 (按照 顺序 ) 


ngx array 七 *codes; 


// 每 一 个 请 求 的 


ngx http script engine tt 脚本 引擎 中 都 会 有 一 个 变量 值 栈 ， 





// 即 上 面 提 到 的 


ngx http variable value 七 *sp， 它 的 大 小 就 是 


stack size 
ngx uint 七 stack size; 
} ngx http rewrite loc conf t; 





从 名 称 就 可 以 看 出 ，ngx http rewrite loc conf {其实 就 是 ngx http rewrite module 模块 在 
location 级 别 的 配置 结构 体 ， 即 每 一 个 location 下 都 会 有 1 个 ngx_http rewrite loc_conf t 结 构 
体 。 如 果 这 个 location 下 没有 脚本 式 配 置 ， 那 么 其 成 员 codes 数 组 就 是 空 的 ， 否 则 codes 数 组 就 
会 放置 承载 着 被 解析 后 的 脚本 指令 的 结构 体 。 


成 员 codes 数 组 的 设计 是 比较 独特 的 。 前 文 我 们 说 过 ， 脚 本 指令 都 是 实现 了 “接口 
ngx_http_ Script code_ pt 的 各 个 不 同 的 充当 “类 ”的 结构 体 ， 这 些 结 构 体 可 以 是 
ngx http script var code t、ngx http Script value code t 等 ， 它 们 的 类 型 不 同 ， 占 用 的 内 存 也 
不 同 ， 如 何 把 它们 整个 放 入 1 个 数组 中 呢 (注意 : 不 是 把 它们 的 指针 放 到 数组 中 ! ) ? 以 下 3 
点 就 可 以 做 到 : 


1)〉codes 数 组 设计 成 每 个 元 素 仅 占 1 个 字 市 的 大 小 ， 也 就 是 说 ， 我 们 不 奢望 一 个 数组 元 
素 就 能 存放 表示 1 个 脚本 指令 的 结构 体 。 





2) 每 次 要 将 1 个 指令 放 入 codes 数 组 中 时 ， 将 根据 指令 结构 体 的 占用 内 存 字 节 数 N， 在 


So Fi 由 A et 组 








成 员 中 。 如 下 所 示 : 





OT 村 
ngx http Script start code(ngx pool 七 pool, ngx array t *codes, size t size) 


{ 








If (*codes == NULL) { 
// codes 数 组 的 每 


1 个 元 素 只 占 


二 


1 个 字 节 


Codes = ngx array create (pool, 256, 1); 
if (codes == NULL) { 
return NULL; 
} 
// 这 个 


size 就 是 类 似 


ngx http script value code 七 表示 脚本 指令 的 结构 体 所 占用 的 内 存 字 节 数 ， 





A// 这 个 


ngx_array_ push n 就 会 直接 创建 


size 个 数组 元 素 ， 仅 用 来 存储 


1 个 表示 指令 的 结构 体 


return ngx array push n(*codes, size); 


} 





3) HTTP 请 求 到 来 、 脚 本 指令 执行 时 ， 每 执行 完 一 个 脚本 指令 的 ngx_http_script_code_pt 
方法 后 ， 该 方法 必须 主动 地 告知 所 属 指令 结构 体 占用 的 内 存 数 N， 这 样 从 当前 指令 所 在 的 
codes 数 组 索引 中 加 上 N 后 就 是 下 一 条 指令 。 





这 样 我 们 就 把 实现 外 部 变量 的 关键 结构 体 都 介绍 了 ， 再 以 图 15-6 来 形象 地 表示 内 存 中 它 
们 之 间 的 关系 。 


图 15-6 以 “set$variable value;” 配 置 项 作为 示例 ， 两 个 HTTP 请 求 《A 和 B)〉 同时 执行 到 该 行 
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脚本 ， 其 中 ，A 请 求 正 准备 执行 值 value 的 指令 ngx http_ script value code t， 而 B 请 求 已 经 执 
行 完 值 的 入 栈 ， 正 要 执行 指令 ngx http_script var code t。ngx http script engine t 脚 本 引擎 的 
sp 成 员 始 终 指 癌变 量 值 栈 里 正 要 操作 的 值 ， 而 jp 成 员 则 始终 指 癌 将 要 执行 的 下 一 条 指令 结构 
体 。 





15.4.2 ”编译 “set”* 脚 本 


仍然 以 set 为 例 看 看 脚本 配置 是 如 何在 Nginx 的 启动 过 程 中 编译 的 。 当 发 现 “set$variable 
value;” 配 置 时 ， 其 编译 流程 (人 处理 set 配 置 的 ngx http rewrite_ set 方 法) 如 图 15-7 所 示 。 


详细 介绍 一 下 图 15-7 的 各 个 步骤 : 
1) 首先 验证 set 后 续 参 数 的 合法 性 ， 例 如 第 1 个 参数 必须 是 以 $ 符 号 开始 的 变量 名 。 


2) 在 15.2.3 节 我 们 介绍 过 定义 内 部 变量 的 ngx http add variable 方 法 ， 添 加 外 部 变量 一 样 
是 调用 这 个 方法 。 需 要 注意 的 是 ， 外 部 变量 是 允许 重复 定义 的 ， 即 可 以 先 执 行 set$variable 
value1 再 执行 set$variable value2， 这 样 当 后 者 调用 ngx http add variable 方法 时 ， 返 回 的 
ngx_http_ Script var code t 结 构 体 其 实 是 前 者 已 经 定义 好 的 。 所 以 对 于 外 部 变量 而 言 ， 
ngx http add variable 方 法 传 入 的 flags 必 须 含 有 NGX _ HTTP VAR CHANGEABLE 标 志 位 ( 参 
见 表 15-2) 。 
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ngx_http_script_engine_ 


ip: 待 执行 指令 





ngx_http_variable_value_t 开 量 值 构 成 的 请 求 A 数 据 栈 ， 变 量 值 解析 时 快速 人 栈 ， 变 量 解析 时 即 出 栈 
Ip: 待 执行 指令 


~ Pi 
请 求 B oO 


ngx_h variahle_value_ t 变 量 值 构成 的 请 求 B 数 据 栈 


[一 









ngx_http_script_value_code_t 


code: 执行 变量 值 压 栈 


text_len=5 





党 








了 
7 text_data=” value” | 
执行 到 哪 就 指向 哪 ” ee 





of /,/ | 


/7 | 
“” 先 解析 变量 值 /再 解析 变 师 各 


ngx_http_rewrite_loc_conf + location 下 所 有 脚本 语 句 构 成 的 
ngx_http_script_XXXTcode_t 数 组 


codes: 脚本 语句 数组 a 





stack_size: 指定 栈 长 度 


图 15-6 ”外 部 变量 实现 的 各 数据 结构 间 的 内 存 关系 示意 图 
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图 中 以 “set$variable value; ”作为 示例 ， 脚 本 由 右 向 左 解析 为 


ngx_http_sctipt_value_code_t、 ngx_http_script_ var_code_t 
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1 ) 验证 set 第 1 个 参数 必须 是 $ 开 头 的 变量 
2 ) 调用 ngx_http_add_variable 方 法 添加 这 个 外 部 变量 
3 ) 调用 ngx_http_get_variable_index 方 法 将 变量 索引 化 处 理 


4 ) 若 变 量 定义 的 get_handler 未 设置 过 ， 量 不 为 5 类 特殊 变量 ， 重 设 get_handler| 访 止 出 错 








5 ) 设置 第 2 个 值 参数 的 脚本 处 理 方法 








5.1 ) 检查 参数 中 是 否 还 有 $ 打 头 的 变量 
[变量 值 含有 其 他 变量 ] 


中， 


[变量 值 中 不 再 含 


变量 ] 


5.2 ) 设置 处 理 字符 串 值 的 指令 ngx_http_script_value_code_t 


5.3 ) 设置 ngx_http_script_complex_value_code_t 处 理 含有 变量 的 值 





6 ) 检查 该 变量 是 否定 义 过 的 内 部 变量 、 且 set_handler 方 法 设置 过 


< 


[set_handler 为 NULL 空 指针 ] 








7) 设置 变量 名 脚本 语句 的 处 理 方法 ngx_http_script_var_code_t 


8 ) 设置 处 理 该 变量 的 方法 为 ngx_http_script_var_handler_code_t 





[变量 被 定义 过 、set_handler 也 设置 过 ] 
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图 15-7 编译 set 脚 本 配置 的 流程 


3) 前 文 我 们 说 过 ， 变 量 是 分 为 定义 和 使 用 两 部 分 的 ， 唯 有 打算 使 用 它 时 才 应 该 索引 
化 ， 把 它 的 值 缓存 到 请 求 的 variables 数 组 中 。 而 对 ngx http rewrite _ module 模块 的 外 部 变量 而 
言 ，set 配 置 既 定义 了 一 个 变量 ， 也 表明 会 使 用 这 个 变量 。 所 以 一 定 会 调用 
ngx_http_get_variable_index 方 法 把 变量 索引 化 的 ， 同 时 索引 值 会 保存 到 
ngx_http_script_var_code t 结 构 体 的 index 成 员 里 (参见 15.4.1 节 )。 





4) 内 部 变量 的 get handler 方 法 是 必须 实现 的 ， 因 为 通常 都 是 采用 “惰性 求 值 ”， 即 只 有 读 
取 这 个 变量 值 时 才 会 去 调用 get_handler 计 算出 这 个 值 。 然 而 外 部 变量 是 不 同 的 ， 每 一 次 set 都 
会 立刻 给 变量 重新 赋值 ， 同 时 读 取 变量 值 时 ， 因 为 变量 值 是 被 索引 化 的 ， 所 以 可 以 直接 从 请 
求 的 variables 数 组 里 取 到 set 后 的 值 。 这 样 get handler 似 乎 是 没有 用 武之 地 的 。 然 而 ， 可 能 
些 模块 会 在 set 脚 本 执行 之 前 就 使 用 到 外 部 变量 了 ， 此 时 外 部 变量 的 值 是 不 存在 的 ， 即 缓存 的 
variables 数 组 里 变量 值 是 空 的 。 从 15.2 节 可 知 ， 此 时 会 调用 get_handler 方 法 来 读 取 变量 值 ， 所 
以 外 部 变量 的 get_handler 方 法 也 不 可 以 为 NULL， 它 被 定义 为 ngx_http_ rewrite var 方 法， 这 个 
方法 所 做 的 唯一 工作 就 是 把 变量 值 置 为 ngx_http variable_null value 空 值 : 





























ngx http variable value t ngx http variable null value = 
ngx http Variable("") 7 








当 第 2 步 添 加 变量 时 获得 的 ngx http_variable t 中 get handler 为 NULL 时 ， 如 果 变 量 名 的 前 
级 属于 5 类 特殊 变量 (参见 表 15-1〉， 那 么 在 所 有 配置 项 解析 完毕 后 (当然 也 包括 脚本 式 配 
置 set) ， 在 图 15-1 的 第 5.2 步 又 中 就 会 给 这 类 变量 重新 设置 get handler 方 法 。 所 以 对 于 非 5$ 类 
特殊 变量 日 get handler 为 NULL 时 ， 就 得 把 get handler 设 置 为 ngx http rewrite var 方法， 使 得 外 
部 变量 未 赋值 时 读 取 它 可 以 获得 空 值 。 











5) 开始 处 理 set 的 第 2 个 值 参数 〈 即 调用 ngx_http_rewrite_value 方 法 处 理 ) 。 





5.1) 这 个 参数 可 以 是 纯 字符 种， 也 可 以 含有 其 他 变量 ， 这 二 者 之 间 的 处 理 方式 是 不 同 
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的 。 所 以 首先 检查 这 第 2 个 值 参数 里 有 没有 $ 符 号 ， 各 像 本 节 的 例子 set$variable value 中 值 中 
是 没有 变量 的 ， 则 跳 到 5.2 执 行 ， 否 则 执行 5.3 步 骤 。 








5.2) 到 这 里 我 们 已 经 可 以 开始 编译 纯 字 符 串 的 变量 值 了 。 束 像 上 一 节 介 绍 的 那样 ， 纯 
字符 串 值 的 指令 结构 体 是 ngx http_script value code t， 我 们 首先 会 把 它 添加 到 所 在 location 下 
的 ngx http _ rewrite loc_conf t 配 置 结构 体 的 codes 数 组 中 ， 如 下 : 





ngx http Script value code t *val; 
val = ngx http Script start code (cf->pool, &lcf->codes, 
sizeof (ngx http Script value code t)); 














接着 ， 如 同 15.4.1 节 介绍 过 的 那样 ， 将 ngx http_script value_code t 的 4 个 成 员 赋 值 : 





n = ngx atoi (value->data, value->len); 
if (n == NGX ERROR) { 





val->code = ngx http Script value code; 





val->value = (uintptr t) n; 
val->text len = (uintptr t) value->len; 
val->text data = (uintptr t) value->data; 





实际 执行 脚本 指令 的 ngx http_script value code 方法 在 下 一 节 介绍 。 


5.3) 如 果 值 参数 中 含有 其 他 变量 ， 那 么 处 理 方式 会 复杂 一 些 。 此 时 
ngx_http_Script_ complex_value_code 多 作为 指令 结构 体 添 加 到 codes 数 组 中 。 本 章 不 对 此 做 详 
细 介 绍 。 











6) 把 变量 值 编译 好 后 ， 再 来 编译 变量 名 。 如 果 set 的 变量 其 实 是 一 个 定义 过 的 内 部 变 
量 ， 那 么 第 2 步 返 回 的 就 是 被 某 个 Nginx 模 块 定 义 过 的 ngx_http_variable t， 它 的 set_ handler 很 


能 设置 过 。 如 条 set_ handler 设 置 过 则 执行 第 8 步 ， 人 否则 执行 第 7 步 。 


9 








7) 大 部 分 情况 下 ， 内 部 变量 不 会 与 外 部 变量 混合 在 一 起 使 用 。 此 时 ， 我 们 首先 把 
ngx_http_script var code t 指 令 结 构 体 添加 到 codes 数 组 中 ， 再 把 变量 的 索引 号 传 到 index 成 
员 ， 并 设置 变量 指定 的 执行 方法 为 ngx http_ script set var code (下 一 节 再 介绍 其 实现 ) ， 如 
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下 所 示 : 





vcode->code = ngx http Script set Var code; 
vcode->index = (uintptr t) index; 








8) 如 果 一 个 内 部 变量 希望 在 nginx.conf 文 件 中 用 set 命 令 修改 其 值 ， 那 么 它 就 会 实现 
set_handler 方 法 ， 意 思 是 ， 执 行 到 set 指 令 时 ， 解 析 变 量 值 时 请 调用 这 个 set_handler 方 法 吧 。 
如 何 实 现 这 一 意图 呢 ? 新 增 一 个 ngx http_ script var handler code tt 指 令 结 构 体 ， 专 门 处 理 这 
种 “内 外 混用 ”的 变量 : 





typedef struct { 





ngx http script code pt code; 
ngx http set variable pt handler; 
Uintptre’t data; 


} ngx http script var handler code t; 








可 以 看 到 它 并 没有 index 成 员 ， 为 什么 呢 ? 因为 set handler 方 法 是 由 内 部 变量 定义 过 的 ， 
这 个 方法 肯定 能 够 找到 变量 值 〈 不 需要 关心 它 是 售 通 过 索引 下 标 ) 。 


当 执 行 到 set 脚 本 指令 设置 这 个 变量 的 值 时 ， 就 调用 set handler 方 法 〈 即 上 面 的 handler 回 
调 方法 ) 处 理 。 


这 一 步 又 就 是 将 ngx http_script var handler code t 指 令 结 构 体 添加 到 codes 数 组 中 ， 并 正 





ngx http script var handler code t *vhcode; 

vhcode = ngx http Script start code(cf->pool, &lcf->codes, 
sizeof (ngx http script var handler code t)); 

vhcode->code = ngx http script var set handler code; 

vhcode->handler = Vv->set handler; 

vhcode->data = Vv->data; 




















它 的 data 成 员 就 被 赋值 为 set 第 2 个 参数 变量 值 ，handler 方 法 则 为 内 部 变量 已 经 定义 过 的 
set handler 方 法 ， 而 code 执 行 指令 方法 则 为 ngx http_script var set handler code， 下 一 节 我 们 


会 详细 介绍 。 


站 由 掉 所 有 所 和 所 掉 由 Phttp' /wNv inuxorobe. con 





1$.4.3 ”脚本 执行 流程 


当 HTTP 请 求 执行 到 NGX _ HTTP _ SERVER_ REWRITE PHASE 或 者 
NGX_HTTP_REWRITE_PHASE 阶 段 时 ， 就 有 可 能 执行 脚本 (前 提 是 加 入 了 
ngx http rewrite module 模块 ， 日 nginx.conf 里 有 该 模块 提供 的 脚本 式 配置 ) 。 图 1$-8 展 示 了 的 





行 脚本 的 ngx http rewrite handler 方 法 主要 流程 。 
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1 ) 获取 请 求 所 属 location 下 的 配置 ngx_http_rewrite_loc_conf t 
[location 下 是 否 存 在 待 执行 脚本 ? ] 








5 ) 执行 脚本 对 应 的 ngx_http_script_code_pt 方 法 
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图 15-8 ”执行 脚本 的 流程 
下 面 将 会 介绍 图 15-8 的 各 步骤 ， 同 时 也 将 介绍 图 15-7 中 第 5.2、7、8 步 中 编译 后 的 指令 : 


1) 首先 获取 location 所 属 的 ngx http rewrite loc_conf tt 结构 体 ， 因 为 所 有 的 脚本 指令 都 保 
存在 它 的 codes 数 组 中 ， 所 以 检查 codes 数 组 是 否 为 NULL 就 可 以 知道 ， 当 前 location 下 是 否 
脚本 配置 存在 。 若 没有 脚本 ， 则 ngx http_ rewrite module 方法 可 以 直接 结 





2) 执行 脚本 前 ， 一 定 要 先 建立 一 个 脚本 引擎 ngx http_script_ engine t， 这 个 结构 体 只 为 


这 个 请 求 、 这 个 location 服 务 。 如 下 : 





ngx http Script engine t *e7 
e = ngx pcalloc(r->pool, sizeof (ngx http script engine 七 ) ) 














3) 建立 变量 值 构 成 的 栈 ， 如 下 所 示 : 





ngx http rewrite loc conf 七 *rlcef; 
rlcf = ngx http get module loc conf(r, ngx http rewrite module); 
e->sp = ngx pcalloc(r->pool, 

rlcf->stack size * sizeof (ngx http variable value t+)); 








4) 所 有 的 脚本 指令 都 在 rlcf>codes 数 组 中 ， 虽 然 每 个 指令 结构 体 大 小 不 一 致 ， 但 有 两 点 
可 以 确定 : 数组 的 第 1 个 成 员 就 是 第 1 个 指令 结构 体 ， 每 个 指令 结构 体 的 第 1 个 成 员 一 定 是 
ngx_http_script code_pt 函 数 指针 ， 所 以 可 以 先 把 让 指向 数组 首 地 址 ， 并 把 ip 强制 转化 为 
ngx_http_script_ code pt 方法 执行 脚本 ， 其 中 每 一 个 方法 负责 把 ip 移 向 下 一 条 待 执行 的 脚本 指 
令 s 如 下 | 





// codes 数 组 第 
1 个 元 素 就 是 第 


1 个 指令 结构 体 


e->ip = rlcf->codes->elts; 


// ip 指 向 
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NULL 时 就 说 明 脚 本 执行 完毕 


while (*(uintptr t *) e->ip) { 
// 每 


1 个 指令 结构 体 的 第 


1 个 成 员 一 定 是 


ngx http script code pt 方法 





code = *(ngx http Script code pt *) e->ip; 
// 执行 指令 方法 时 ， 该 方法 负责 移动 





ip 指 针 


code (e); 





5) 现在 我 们 可 以 详细 看 看 每 条 脚本 指令 执行 时 到 底 是 如 何 工 作 的 。 图 15-7 中 第 5.2 步 里 
编译 了 一 条 执行 纯 字 符 串 值 的 脚本 指令 结构 体 ， 它 在 上 面 的 code(e) 执 行 时 方法 为 
ngx_http_ Script value _ code， 看 看 到 底 做 了 些 什 么 : 








void 
ngx http Script value code (ngx http Script engine 七 *e) 
{ 








ngx http script value code 七 *code; 


// 由 于 





ngx http script code pt 是 指令 结构 体 的 第 





IT 个 成 员 ， 所 以 


ip 同时 也 指向 了 指令 结构 体 。 


// 对 于 编译 纯 字 符 串 变量 值 而 言 ， 其 指令 结构 体 为 


ngx http script value code 七 ， 这 样 ， 





// 就 从 
codes 数 组 中 取 到 了 指令 结构 体 


code 
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// 为 了 能 够 执行 下 一 条 脚本 指令 ， 先 把 


ip 移 到 下 一 个 指令 结构 体 的 地 址 上 。 移 动 方式 很 简单 ， 


// 右 移 


sizeof (ngx http script value code 七 ) 字 节 即 可 





e->ip += sizeof (ngx http Script value code 七 ) 


// e->sp 指 向 了 栈 顶 元 素 ， 处 理 脚 本 变量 值 时 ， 先 把 这 个 值 赋 给 栈 顶 元 素 








e->sp->len = code->text len; 
e->sp->data = (u char *) code->text data; 


// 栈 自动 上 移 


e->spt++; 





当 变 量 是 普通 的 外 部 变量 时 ， 图 15-7 中 第 7 步 设置 了 变量 名 的 指令 执行 方法 为 
ngx http_script_ set var code， 看 看 它 是 如 何 与 变量 值 栈 配合 的 : 





void 
ngx http Script set Var code(ngx http Script engine 七 *e) 
{ 








ngx http request t 工 7 
ngx http Script var coae t code; 


// 同样 由 指向 





ngx http script set var code 方 法 的 指针 





ip 可 以 获取 到 


ngx http script 
// var_code 七 指令 结构 体 


code = (ngx http Script var code t *) e->ip; 


// 将 





ip 移 到 下 一 个 待 执行 脚本 指令 


e->ip += sizeof (ngx http Script var code t); 
r= e->request; 


// 首先 把 栈 下 移 ， 指 向 





ngx http script value coqe 设 置 的 那个 纯 字 符 串 的 变量 值 


口 由 掉 岂 有 所 和 所 掉 由 http' /wNv inuxorobe. con 








e->sp--; 


// 根据 


ngx http script var code 七 的 





indqex 成 员 ， 可 以 获得 被 索引 的 变量 值 


// r->variables [code->index] ,以 下 
5 行 语句 就 是 用 
e->SsP 栈 里 的 字符 串 来 设置 这 个 变量 值 
z->Variables [codqe->indqex]l.1len = e->sp->len; 


] 
r->variables[code->index] .valid = 1; 
r->variables[code->index] .no cacheable = 0; 
J 
]。 





r->variables[code->index] .not found = 0; 
r->variables[code->index] .data = e->sp->data; 








如 果 set 的 变量 是 像 args 这 样 的 内 部 变量 ， 它 的 处 理 方法 又 有 不 同 。 因 为 args 变 量 的 
set handler 方 法 不 为 NULL， 看 看 它 的 定义 : 





static ngx http variable t ngx http core variables[] = { 
{ ngx string("args"), 
// set handler 方 法 不 是 





NULL 
ngx http variable request set, 
ngx http variable request, 
offsetof(ngx http request t, args), 
// 允许 


set 脚 本 来 重新 设置 这 个 





args 变 量 ， 所 以 必须 使 


flags 标 志 位 具有 





NGX HTTP VAR CHANGEABLE 
NGX HTTP VAR CHANGEABLE|NGX HTTP VAR NOCACHEABLE, 0 }, 






































在 图 15-7 的 第 8 步 中 ， 对 于 设置 了 set_handler 的 变量 ， 它 的 脚本 指令 执行 方法 为 
ngx http script var set handler code， 看 看 它 的 实现 : 
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void 
ngx http Script var set handler code(ngx http script engine t *e) 
{ 








ngx http Script var handler code 七 *code; 


// 同样 获取 到 指令 结构 体 








code = (ngx http script var handler code t *) e->ip; 
// 移动 





ip 到 下 一 条 待 执行 指令 


e->ip += sizeof (ngx http Script var handler code t+); 


// 变量 值 栈 移 动 





e->sp--; 
// 将 请 求 、 变 量 值 传递 给 


set handler 方 法 执行 它 





code->handler (e->request, e->sp, code->data); 





所 有 的 脚本 指令 执行 时 都 与 上 面 3 个 例子 相似 ， 读 者 朋友 可 以 通过 阅读 源 代 码 掌 握 
ngx http rewrite _ module 模块 的 更 多 脚本 实现 原理 。 
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15S 小 车 


本 章 由 浅 入 深 地 先 从 如 何 使 用 内 部 变量 说 起 ， 进 而 分 析 了 内 部 变量 的 工作 原理 ， 包 括 定 
义 、 使 用 时 各 部 分 是 如 何 配合 使 用 的 ， 再 以 一 个 例子 说 明 如 何 定义 新 的 内 部 变量 《未 使 用 的 
供 入 式 变量 ) 。 

外 部 变量 是 由 ngx_http_rewrite_module 模 块 引入 的 ， 本 章 后 半 部 分 说 明了 该 模块 的 脚本 引 
擎 是 如 何 实现 外 部 变量 的 ， 包 括 脚本 在 Nginx 月 动 时 的 编译 与 HTTP 请求 到 来 时 的 执行 ， 并 分 
析 了 内 部 变量 如 何 与 外 部 变量 混合 着 使 用 。 








读者 朋友 通过 阅读 本 间 ， 可 以 在 开发 HTTP 模 块 时 很 轻松 地 使 用 HTTP 变 量 ， 甚 至 可 以 通 
过 对 比 ngx_http_rewrite_module 模 块 的 实现 ， 在 自己 的 模块 中 开发 新 的 脚本 引擎。 
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第 16 童 ”slab 共享 内 存 








许多 场景 下 ， 不 同 的 Nginx 请 求 间 必须 交互 后 才能 执行 下 去 ， 例 如 限制 一 个 客户 端 能 够 
并 发 访问 的 请 求 数 。 可 是 Nginx 被 设计 为 一 个 多 进程 的 程序 ， 服 务 更 健壮 的 为 一 面 束 是 ， 
Nginx 请 求 可 能 是 分 布 在 不 同 的 进程 上 的 ， 当 进程 间 需 要 互相 配合 才能 完成 请 求 的 处 理 时 ， 
进程 间 通 信 开 发 困难 的 特点 就 会 凸显 出 来 。 第 14 重 介绍 过 一 些 进程 间 的 交互 方法 ， 例 如 14.2 
节 的 共有 圣 内 存 。 然 而 如 果 进 程 间 需要 交互 各 种 不 同 大 小 的 对 象 ， 需 要 共 译 一 些 复 洒 的 数据 结 
构 ， 如 链表 、 树 、 图 等 ， 那 么 这 些 和 内容 将 很 难 文 撑 这 样 复 杂 的 语义 。Nginx 在 14.2 节 共 孚 和 内存 
的 基础 上 ， 实 现 了 一 套 高 效 的 slab 内 存 管 理 机 制 ， 可 以 帮助 我 们 快速 实现 多 种 对 象 间 的 跨 
Nginx worker 进 程 通 信 。 本 章 除 了 说 明 如 何 使 用 它 以 外 ， 同 时 还 会 详细 介绍 实现 原理 ， 从 中 
我 们 可 以 发 现 它 的 设计 初衷 及 不 适用 的 场景 。Slab 实 现 的 源 代码 非常 高 效 ， 然 而 却 也 有 些 生 
座 ， 本 章 会 较 多 地 通过 源 代码 说 明 各 种 二 进 制 位 操作 ， 以 帮助 读者 朋友 学 习 slab 的 编码 艺 
术 。 
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16.1 操作 slab 共 享 内 存 的 方法 





操作 slab 内 存 池 的 方法 只 有 下 面 5 个 : 





// 初始 化 新 创建 的 共享 内 存 


void ngx Slab init(ngx Slab pool 七 *pool); 


// 加 锁 保 护 的 内 存 分 配方 法 


void xngx slab alloc(ngx slab pool 上 *pool，size 七 size); // 不 加 锁 保 护 的 内 存 分 配方 法 


void *ngx slab alloc locked(ngx slab pool tt *pool，size t size); // 加 锁 保护 的 内 存 释放 方法 


void ngx slab free (ngx slab pool t *pool，vVoiqd *p); // 不 加 锁 保护 的 内 存 释 放 方 法 


void ngx slab free locked(ngx slab pool t *pool, void *p); 








这 5 个 方法 是 src/core/ngx_slab.h 里 仪 有 的 5 个 方法 ， 其 精简 程度 可 见 一 斑 。ngx_slab_init 由 
Nginx 框 架 自 动 调 用 ， 使 用 slab 内 存 池 时 不 需要 关注 它 。 通 常 要 用 到 slab 的 都 是 要 跨 进 程 通信 
的 场景 ， 所 以 ngx slab alloc locked 和 ngx slab free locked 这 对 不 加 锁 的 分 配 、 释 放 内 存 方法 
较 少 使 用 ， 除 非 模 块 中 己 经 有 其 他 的 同步 锁 可 以 复 有 用。 因此， 模块 开发 时 分 配 内 存 调用 
ngx_slab_alloc， 参 数 size 就 是 需要 分 配 的 内 存 大 小 ， 返 回 值 就 是 内 存 块 的 首 地 址 ， 共 享 内 存 
用 尽 时 这 个 方法 会 返回 NULL; 释放 这 块 内 存 时 调用 ngx_slab_free， 参 数 p 就 是 ngx_slab_alloc 
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返回 的 内 存 地 址 。 还 有 一 个 参数 ngx slab pool tspool 又 是 怎么 来 的 呢 ? 


很 简单 ， 由 下 面 的 ngx shared _ memory add 方 法 即 可 拿 到 必须 的 ngx Slab pool t*pool 参 
数 : 





// 告诉 


Nginx 初 始 化 


1 块 大 小 为 


size、 名 称 为 


name 的 


slab 共 享 内 存 池 


ngx shm zone t ngx shared memory add (ngx conf t cf, ngx str 七 name size t size, void tag); 








ngx_shared_memory add 需 要 4 个 参数 ， 从 第 1 个 参数 ngx_conf tscf 的 配置 文件 结构 体 就 可 
以 推测 出 ， 该 方法 必须 在 解析 配置 文件 这 一 步 中 执行 。 所 以 在 ngx_command t 里 定义 的 配置 
项 解析 方法 中 可 以 拿 到 ngx_conf t*cf， 通 常 ， 我 们 都 会 在 配置 文件 里 设置 共享 内 存 的 大 小 。 
当然 ， 各 http 模 块 都 是 在 解析 http{} 配 置 项 时 才 会 被 初始 化 ， 定 义 http 模 块 时 ngx_http_module { 
的 8 个 回调 方法 里 也 可 以 拿 到 ngx_conf txcf。 








参数 ngx_str_t*name 是 这 块 slab 共 享 内 存 池 的 名 字 。 显 而 易 见 ，Nginx 进 程 中 可 能 会 有 许多 
个 slab 内 存 池 ， 而 且 ， 有 可 能 多 处 代码 使 用 同一 块 slab 内 存 池 ， 这 样 才 有 必要 用 唯一 的 名 字 
来 标识 每 一 个 slab 内 存 池 。 


参数 size tsize 设 置 了 共享 内 存 的 大 小 。 


到 尝 人 ed 生生 生生 全 合生 下 的 NE 和 全 押 写 交 凡 调 丰 各 撤 和 BEEb 帮 节 





从 而 造成 数据 错乱 。 所 以 ， 通 常 可 以 把 tag 参 数 传 入 本 模块 结构 体 的 地 址 。tag 参 数 会 存放 在 
ngx shm zone t 的 tag 成 员 中 。 


@ ,is 当 我 们 执行 -s reload 命 令 时 ，Nginx 会 重新 加 载 配置 文件 ， 此 时 ,会 触发 再 次 
初始 化 slab 共 享 内 存 池 。 而 在 该 过 程 中 ，tag 地 址 同样 将 用 于 区 分 先后 两 次 的 初始 化 是 否 对 应 
于 同一 块 共享 内 存 。 所 以 ，tag 中 应 传 入 全 局 变量 的 地 址 ， 以 使 两 次 设置 tag 时 传 入 的 是 相同 
地 址 。 


如 果 前 后 两 次 设置 的 tag 地 址 不 同 ， 则 会 导致 即使 共享 内 存 大 小 没有 变化 ， 旧 的 共享 内 存 
也 会 被 释放 挤 ， 然 后 再 重新 分 配 一 块 同样 大 小 的 共享 内 存 ， 这 是 没有 必要 的 。 





ngx_shared memory add 的 返回 值 就 是 用 来 拿 到 ngx_slab_pool tspool 的 ， 如 果 返 回 NULL 
表示 获取 共享 内 存 失败 。 如 果 参 数 name 己 经 存在 ，ngx_shared memory _ add 会 比较 前 一 次 name 
对 应 的 共享 内 存 size 是 否 与 本 次 size 参 数 相等 ， 以 及 tag 地 址 是 否 相 等 ， 如 果 相等 ， 直 接 返 回 
上 一 次 的 共享 内 存 对 应 的 ngx_shm zone t， 否 则 会 返回 NULL。ngx_shm zone t 究 竟 是 怎样 帮 
助 我 们 拿 到 ngx slab pool t*pool 的 呢 ? 














先 来 看 看 ngx shared memory add 返 回 了 一 个 怎样 的 结构 体 : 





typedef struct ngx shm zone s ngx shm zone t; struct ngx shm zone S { 





// 在 真正 创建 好 


slab 共 享 内 存 池 后 ， 就 会 回调 


injit 指 向 的 方法 


ngx shm zone init pt init; 





/7 当 
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ngx shm zone init pt 方法 回调 时 ， 通 常 在 使 用 





slab 内 存 池 的 代码 前 需要 做 一 些 初始 化 工作 ， 


// 这 一 工作 可 能 需要 用 到 在 解析 配置 文件 时 就 获取 到 的 一 些 参数 ， 而 


data 主 要 担当 传递 参数 的 职责 


void *data; 


// 描述 共享 内 存 的 结构 体 


ngx shm t shm; 


// 对 应 于 


ngx shared memory add 的 





tag 参 数 


void ras re 





拿 到 了 ngx_shm zone tt 结构 体 后 ，init 成 员 是 必须 要 设置 的 ， 因 为 Nginx 后 续 创 建 好 slab 内 
存 池 后 ， 一 定 会 调用 init 指 向 的 方法 ， 这 是 约定 好 的 。ngx_shm _zone_init_pt 函 数 指针 定义 如 
下 : 





typedef ngx int t (*ngx shm zone init pt) (ngx shm zone t zone, void data); 
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我 们 需要 实现 一 个 这 样 的 方法 ， 然 后 赋 给 ngx_shm zone t 的 init 函 数 指针 。 这 个 方法 被 回 
调 时 ， 其 第 1 个 参数 就 是 ngx_shared_memory add 返 回 的 ， 而 且 是 刚刚 设置 过 其 init 函 数 指针 成 
员 的 ngx shm zone tt 结构 体 。 对 于 ngx shm zone init pt 的 第 2 个 参数 void*data， 在 理解 它 之 前 
先 要 搞 清楚 Nginx 的 reload 重 载 配 置 文件 流程 。 重 新 解析 配置 文件 意味 着 所 有 的 模块 (包括 
http 模 块 ) 都 会 重新 初始 化 ， 然 而 ， 之 前 正 处 于 使 用 中 的 共享 内 存 可 能 是 有 数据 的 、 可 以 复 
用 的 ， 如 果 丢 弃 了 这 些 旧 数据 而 重新 开辟 新 的 共享 内 存 ， 是 会 造成 严重 错误 的 。 所 以 如 果 处 
于 重读 配置 文件 流程 中 ， 会 尽 可 能 地 使 用 旧 共 享 内 存 〈 如 果 存 在 的 话 ) ， 表 现在 
ngx_shm zone _init_ pt 的 第 2 个 参数 voidsdata 上 时 ， 就 意味 着 : 如 果 Nginx 是 首次 启动 ，data 则 为 
空 指针 NULL; 若是 重读 配置 文件 ， 由 于 配置 项 、http 模 块 的 初始 化 导致 共享 内 存 再 次 创建 ， 
那么 data 就 会 指向 第 一 次 创建 共享 内 存 时 ，ngx_shared memory add 返 回 的 ngx shm_ zone t 中 的 
data 成 员 。 读 者 朋友 在 处 理 data 参 数 时 请 务必 考虑 以 上 场景 ， 考 虑 如 何 使 用 老 的 共享 内 存 ， 
以 避免 不 必要 的 错误 。 
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16.2 ”使 用 slab 共 享 内 存 池 的 例子 








假定 这 样 一 个 场景 : 对 于 来 自 于 同一 个 人 PP 的 请 求 ， 如 果 客 户 站 访问 某 一 个 URL 并 且 获 得 
成 功 ， 则 认为 这 次 访问 是 重量 级 的 ， 但 需要 限制 过 于 频率 的 访问 。 因 此 ， 设 计 一 个 http 过 滤 
模块 ， 大 访问 来 自 同一 个 了 下 且 URL 相 同 ， 则 每 N 秒 钟 最 多 只 能 成 功 访 问 一 次 。 例 如 ， 设 定 10 
秒 钟 内 仪 能 成 功 访问 1 次 ， 那 么 某 浏 览 器 0 秒 时 访问 /method/access 成 功 ， 在 第 1 秒 奉 仍然 收 到 
来 自 这 个 人 的 相同 请 求 ， 将 会 返回 403 拒 绝 访 问 。 直 到 第 11 秒 ， 这 个 JP 访问 /method/access 才 
会 再 次 成 功 。 








现在 来 实现 这 样 的 模块 。 首 先 ， 产 品级 的 Nginx 一 定 会 有 多 个 worker 进 程 ， 来 自 同 一 个 IP 
的 多 次 TCP 连 接 有 可 能 会 进入 不 同 的 worker 进 程 处 理 ， 所 以 需要 用 共享 内 存 来 存放 用 户 的 访 
问 记 录 。 为 了 局 效 地 查找 、 插 入 、 删 除 访问 记录 ， 可 以 选择 用 Nginx 的 红 黑 树 来 存放 它们 ， 
其 中 关键 字 就 是 PP+URL 的 字符 串 ， 而 值 则 记录 了 上 次 成 功 访 问 的 时 间 。 这 样 请 求 到 来 时 ， 
以 IP+URL 组 成 的 字符 串 为 天 键 字 伍 询 红 黑 树 ， 没 有 查 到 或 但 到 后 发 现 上 次 访问 的 时 间距 现 
在 大 于 人 菏 个 阀 值 ， 则 允许 访问 ， 同 时 将 该 键 值 对 插 下 红 黑 树 ; 反之 ， 硝 但 到 了 且 上 次 访问 的 
时 间距 现在 小 于 茶 个 阀 值 ， 则 拒绝 访问 。 





考虑 到 共 至 内 存 的 大 小 有 限 ， 长 期 运行 时 如 果 不 考 虑 回收 不 活跃 的 记录 ， 那 么 一 方面 红 
黑 树 会 越发 巨大 从 而 影响 效率 ， 必 一 方面 共享 内 存 会 很 快 用 尽 ， 导 致 分配 不 出 新 的 结 点 。 所 
以 ， 所 有 的 络 点 将 通过 一 个 链表 连接 起 来 ， 其 插入 顺序 按 了 PHURL 最 后 一 次 访问 的 时 间 组 
织 。 这 样 可 以 从 链表 的 首部 插入 新 访问 的 记录 ， 从 链表 尾部 取出 最 后 一 行 记录 ， 从 而 检查 是 
个 需要 淘汰 出 共 胖 内 存 。 由 于 最 后 一 行 记 录 一 定 是 最 老 的 记录 ， 如 果 它 不 需要 淘汰 ， 也 就 不 
再 要 继续 过 历 链 表 】， 因 此 可 以 提高 执行 效率 。 























下 面 按照 以 上 设计 实现 一 个 http 过 滤 模 块 ， 以 此 作为 例子 说 明 slab 共 侍 内 存 池 的 用 法 。 
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16.2.1 共享 内 存 中 的 数据 结构 








对 于 每 一 条 访问 记录 ， 需 要 包含 3 条 数据 : IP+HURL 的 变 长 字符 串 (URIL 长 度 变化 范围 很 
大 ， 不 能 按照 最 大 长 度 分 配 等 长 的 内 存 存 放 ， 这 样 太 浪费 ) 、 摘 述 红 黑 树 结 皮 的 结构 体 、 最 
近 访 问 时 间 。 如 果 为 每 条 记录 分 配 3 块 内 存 各 目 独 并 存放 ， 似 乎 是 很 自然 的 、 符 合 软件 工程 
的 行为 。 然 而 ， 应 当 考 虑 到 Slab 内 存 管理 机 制 因 为 强调 速度 而 及 用 了 best-fit 思 想 ， 这 么 做 会 
产生 最 大 1 倍 内 存 的 浪费 ， 所 以 ， 在 设计 数据 存储 时 应 当 上 尽量 把 1 条 记录 的 3 条 数据 放 在 1 块 连 
续 内 存 上 。 如 何 实现 呢 ? 























先 回 顾 下 7.5.3 节 中 给 出 的 ngx rbtree_ node t 的 定义 : 





typedef struct ngx rbtree node s ngx rbtree node t; struct ngx rbtree node s { 





// 每 个 结 点 的 


hash 值 


ngx rbtree key t key; 


/7 生子 结 点 ,由 


Nginx 红 黑 树 自动 维护 


ngx_ rbtree node t *]GEt 


// 帮 予 结 点 ; 册 
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Nginx 红 黑 树 自动 维护 


ngx rbtree node t *right; 


LX 改革 点 ; 由 


Nginx 红 黑 树 自动 维护 


ngx rbtree node t *parent; 


// 红色 、 黑 色 ， 由 


Nginx 红 黑 树 自动 维护 


u char QOLOr? 
// 无 用 
u_char data; 





红 黑 树 中 的 每 个 结 点 都 对 应 着 一 个 ngx_rbtree_node t 结 构 体 ,. 它 的 key 成 员 必 须要 设置 ， 
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因为 比较 哈 希 过 的 整 型 要 比 挨个 比较 字符 串 中 的 


其 他 成 员 由 ngx rbtree 自 行 处 理 。 





上 Ar 


子 - 付 " 


决 得 多 ! 它 的 data 成 员 目 前 是 无 用 的 ， 


接着 ngx_rbtree_ node t 的 color 成 员 之 后 (和 窗 新 data 成 员 ) ， 开 始 定义 我 们 的 结构 体 


ngx http testslab node t， 如 下 所 示 : 





typedef struct { 


// 对 应 于 


ngx rbtree node tt 最 后 一 个 


data 成 员 
Shas rbtree node data; 
ngx queue t queue; 


// 上 一 次 成 功 访问 该 


URL 的 时 间 ， 精 确 到 毫秒 


ngx msec t last; 


// 按 先后 顺序 把 所 有 访问 结 点 串 起 ， 方 便 淘汰 过 期 结 点 
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IP 地 址 与 


URL 组 合 而 成 的 字符 串 长 度 


u short len; 


// 以 字符 囊 保存 客户 端 


IP 地 址 与 


u char data[l]; } ngx http testslab node t; 








ngx http_testslab_ node t 上 接 ngx rbtree node t、 下 接 变 长 字符 串 ， 一 条 访问 记录 就 是 这 
样 存 放 在 一 块 连续 内 存 上 的 ， 如 图 16-1 所 示 。 
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nex_rbtree_node_t 的 data 成 员 地 址 可 ngx_http_testslab_node_1 
直接 转换 为 ngx_ht tp_test slab_n )( le 1 的 lata 成 员 地 址 可 直接 转换 为 1 p+u r| 


结构 体 的 字符 串 








PR 
nex_rhtree_n , 


ode_1 ngx_http_test 


slal )_nNod le 1 


图 16-1 用 一 段 连续 内 存 存放 红 黑 树 键 、 值 的 内 存 布局 
由 于 多 个 进程 都 要 操作 红 黑 树 ， 描 述 红 黑 树 的 ngx _rbtree_t 和 哨兵 结 点 ngx Tbtree_ node t{ 











都 必须 存放 在 共享 内 存 中 ， 同 理 ， 淘 汰 链表 的 表 头 也 需要 存放 在 共享 内 存 中 ， 因 此 下 面 来 定 
义 结 构 体 ngx_ http_ testslab shm t， 它 会 存放 在 自 进 程 启动 起 从 slab 共 享 内 存 里 分 配 的 第 1 块 内 
存 中 : 








// ngx http testslab shm tt 保存 在 共享 内 存 中 


typedef struct { 


// 红 黑 树 用 于 快速 检索 


ngx_ rbtree t rbtree; // 使 用 


Nginx 红 黑 树 必须 定义 的 哨兵 结 点 
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ngx rbtree node t sentinel; // 所 有 操作 记录 构成 的 淘汰 链表 


ngx queue 七 queue; } ngx http testslab shm t; 











我 们 在 哪里 存放 来 自 共享 内 存 的 ngx_http_testslab_shm t 结 构 体 的 指针 呢 ?” 在 这 个 例子 
中 ， 由 于 仪 有 一 个 http 介 块 下 的 main 级 别 配置 项 ， 这 意味 着 对 这 个 模块 而 言 每 个 worker 进 程 
仅 含 一 个 main 配 置 结 构 体 ， 因 此 ， 可 以 把 ngx http_testslab_shm t 的 指针 放 在 这 个 结构 体 里 。 


此 外 ， 描 述 slab 共 享 内 存 的 ngx slab pool t 狗 构 体 指针 也 可 以 这 样 放置 。 所 以 ， 我 们 定 
义 的 配置 结构 体 ngx http_ testslab_conf t 就 是 这 样 的 : 





// 注意 : 


ngx_http testslab conf 七 不 是 放 在 共享 内 存 中 的 


typedef struct { 


// 共享 内 存 大 小 


SSize. 志 shmsize; 


// 两 次 成 功 访问 所 必须 间隔 的 时 间 
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ngx int t interval; 


// 操作 共享 内 存 一 定 需要 


ngx slab pool 七 结构 体 


// 这 个 结构 体 也 在 共享 内 存 中 


ngx slab pool t *shpool; // 指向 共享 内 存 中 的 


ngx_http testslab shm 七 结构 体 


ngx http testslab shm 七 * sh; 


} ngx http testslab conf 七 











shmsize 和 interval 成 员 仅 为 nginx.conf 里 的 配置 项 ， 其 中 interval 还 用 于 表示 是 售 通 过 配置 
项 开启 了 模块 的 功能 。 





16.2.2 ”操作 共享 内 存 中 的 红 黑 树 与 链表 








在 7.2 节 中 介绍 过 双向 链表 ， 它 的 操作 很 简单 ， 在 这 个 例子 中 当 需 要 删除 结 点 时 调用 


ee ee 证 [站 商 年 不同 由 作 链 内 BLP 和 PE 以 获 





取 到 尾部 的 结 点 ， 而 插入 新 结 点 时 用 ngx queue insert head 方法 插入 链表 首部 即 可 。 


在 7.5 节 中 介绍 过 红 黑 树 ， 删 除 结 点 时 调用 ngx rbtree delete 方 法 即 可 ， 由 于 参数 中 直接 
传递 的 是 结 点 指针 ， 因 此 这 里 不 需要 做 任何 处 理 。 但 是 插入 、 遍 历时 就 稍 复 杂 些 ， 因 为 每 个 
结 点 的 真实 关键 字 是 一 个 变 长 字符 串 ，ngx_rbtree_node t 中 的 key 成 员 放 的 是 字符 串 的 hash 
值 ， 所 以 插入 函数 时 不 能 直接 使 用 预 置 的 ngx_rbtree_ insert_value 方 法 。 我 们 需要 定义 一 个 新 
的 insert 方 法 ， 并 在 初始 化 红 黑 树 时 把 该 方法 传递 给 ngx_rbtree_init 的 第 3 个 参数 。 当 然 ， 定 义 
一 个 新 的 insert 方 法 没有 想象 中 那么 难 ， 只 需要 参考 ngx_rbtree_insert_value 方 法 的 实现 即 可 ， 
该 方法 认为 ngx_rbtree_node t 中 的 key 成 员 就 是 关键 字 ， 而 我 们 则 认为 字符 串 才 是 真正 的 关键 
字 ，key 仅 用 于 加 速 操作 红 黑 树 ， 所 以 稍微 改 改 就 可 以 用 了 。 





读者 朋友 在 继续 阅读 前 可 以 先 浏 览 下 src/core/ngx rbtree.c 中 的 ngx rbtree insert value 方 法 
源码 ， 这 里 不 再 列 出 。 





void 


ngx rbtree insert Value (ngx rbtree node t temp, ngx rbtree node t node, ngx rbtree node t *sentinel) 











接着 ， 开 始 实现 针对 图 16-1 中 这 种 内 存 布局 记录 的 红 黑 树 插 入 方法 


nex http testslab rbtree insert value: 





static void 








ngx http testslab rbtree insert Value (ngx rbtree node 七 *temp, ngx rbtree node t node, ngx rbtree node t sentim 
ngx rbtree node t **p; 
ngx http testslab node t Jn Lrnt; For ( 3 ) A 


// ngx rbtree node 七 中 的 
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key 仅 为 


hash 值 


// 先 比较 整 型 的 


key 可 以 加 快 插 入 速度 


if (node->key < temp->key) { 





p= &temp->left; 


} else if (node->key > temp->key) { 





p= &temp->right; 


} else { /* node->key == temp->key */ 





// 从 


data 成 员 开 始 就 是 


ngx http testslab node 结构 体 


lrn = (ngx http testslab node t *) &node->data; lrnt = (ngx http testslab node 七 *) &temp->data; P : 
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if (*p == sentinel) { 


break; 


temp = *p; 


*p = node; 


node->parent = temp; 








node->left = sentinel; 


node->right = sentinel; 


ngx_ rbt red (node); 





在 实现 了 插入 方法 后 ， 就 可 以 像 下 面 这 样 初始 化 红 黑 树 了 : 





ngx http testslab conf t *conf; ... 


ngx rbtree init(&conf->sh->rbtree, &conf->sh->sentinel, ngx http testslab rbtree insert value); 








下 面 ， 我 们 开始 实现 含有 业务 逻辑 的 ngx_http_testslab lookup 和 ngx http_testslab_expire 方 
法 ， 前 者 含有 红 黑 树 的 衣 历 。 


ngx_http_testslab lookup 负 责 在 htp 请 求 到 来 时 ， 首 先 利 用 红 黑 树 的 快速 检索 特性 ， 看 一 
看 共 孚 内 存 中 是 人 否 存在 访问 记录 。 碍 找 记 录 时 ， 首 先 碍 找 hash 值 ， 厨 相同 再 比较 字符 串 ， 在 
该 过 程 中 都 按 左 子 树 小 于 右 子 树 的 规则 进行 。 如 果 碍 找到 访问 记录 ， 则 检查 上 次 访问 的 时 间 


距 当 前 的 时 间 差 是 否 超 过 允许 阀 值 ， 超 过 了 则 更 新 上 次 访问 的 时 间 ， 并 把 这 条 记录 重新 放 到 
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双向 链表 的 首部 《因为 眼下 这 条 记录 最 不 容易 被 淘汰 ) ， 同 时 返回 NGX DECLINED 表 示人 多 
许 访问 ; 若 没有 超过 阀 值 ， 则 返回 NGX _HTTP _ FORBIDDEN 表 示 拒 绝 访 问 。 如 果 红 黑 树 中 没 
有 查找 到 这 条 记录 ， 则 向 slab 共 享 内 存 中 分 配 一 条 记录 所 需 大 小 的 内 存 块 ， 并 设置 好 相应 的 
值 ， 同 时 返回 NGX_DECLINED 表 示人 允许 访问 。 代 码 如 下 : 








// Ir 是 


http 请 求 ， 因 为 只 有 请 求 执行 时 才 会 调用 


ngx _ http testslab lookup 


// conf 是 全 局 配置 结构 体 


// data 和 


len 参 数 表 示 


IP+URL 字 符 串 ， 而 


hasnh 则 是 该 字符 串 的 


hash 值 


static ngx_int t 


NNnnn http://wWwWwWw linuxorobe. con 





ngx httpP testslab lookup(ngx http request t *r, ngx http testslab conf 七 *conf, 


ngx uint t hash, 


u char* data, 


size t len) 


size t size; 

ngx int t EO 

ngx time t *tp; 

ngx msec t now; 

ngx msec int t ms; 

ngx rbtree node t *node, *sentinel; ngx http testslab node 七 *1lr; 


// 取 到 当前 时 间 


tp = ngx timeofday (); 





now = (ngx msec t) (tp->sec * 1000 + tp->msec); node = conf->sh->rbtree.root; 
sentinel = conf->sh->rbtree.sentinel; while (node != sentinel) { 
// 先 由 
hash 值 快速 查找 请 求 
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if (hash < node->key) { 
node = node->left; 


continue; 
if (hash > node->key) { 
node = node->right; 


continue; 


/* hash == node->key */ 


lr = (ngx http testslab node t *) g&node->data; // 精确 比较 


IP+URL 字 符 串 


rc = ngx memn2cmp (data, lr->data, len, (size t) lr->len); if (rc == 0) { 


// 找到 后 先 取得 当前 时 间 与 上 次 访问 时 间 之 差 


ms = (ngx msec int t) (now - lr->last); // 判断 是 否 超 过 阀 值 
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// 允许 访问 ， 则 更 新 这 个 结 点 的 上 次 访问 时 间 


lr->last = now; 


// 不 需要 修改 该 结 点 在 红 黑 树 中 的 结构 


// 但 需要 将 这 个 结 点 移动 到 链表 首部 


ngx queue remove (&Lr->queue); ngx queue _ insert head(&conf->sh->queue, &lr->queue); // 返回 








NGX_DECLINED 表 示 当 前 











handler 允 许 访问 ， 继 续 向 下 执行 ， 参 见 


10.6.7 节 














return NGX DECLINED; 
} else 1{ 


// 向 客户 端 返回 


口 由 掉 所 有 所 和 所 掉 由 http' /wNv inuxorobe. con 





403 拒 绝 访问 ， 参 


BS 
加 


0 .五 .7 和 


return NGX HTTP FORBIDDEN; } 





node = (rc < 0) node->left : node->right; } 


// 获取 到 连续 内 存 块 的 长 度 


size = offsetof (ngx rbtree node t, data) + offsetof (ngx http testslab node t, data) + len; 


// 首先 尝试 淘汰 过 期 


node ， 以 释放 出 更 多 共享 内 存 


ngx http testslab expirel(r, conf); 


// 释放 完 过 期 访问 记录 后 就 有 更 大 机 会 分 配 到 共享 内 存 


// 由 于 已 经 加 过 锁 ， 所 以 没有 调用 
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node = ngx slab alloc locked(conf->shpool, size); if (node == NULL) { 


// 共享 内 存 不 足 时 简单 返 错 ， 这 个 简单 的 例子 没有 做 更 多 的 处 理 


return NGX ERROR; 





// key 里 存放 
ip+url 字 符 串 的 


hash 值 以 加 快 访问 红 黑 树 的 速度 


node->key = hash; 


lr = (ngx http testslab node t *) &node->data; // 设置 访问 时 间 


lr->last = now; 


// 将 连续 内 存 块 中 的 字符 囊 及 其 长 度 设置 好 


lr=>lLen = (UU char) 
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ngx memcpy (lr->data, data, len); 


// 插入 红 黑 树 


ngx rbtree insert(&conf->sh->rbtree, node); // 插入 链表 首部 


ngx queue insert head(&conf->sh->queue，&lr->queue); // 允许 访问 ， 参 见 





L067 芝 





return NGX DECLINED; 

















ngx_http_testslab_expire 方 法 则 负责 从 双 辣 链表 的 尾部 开始 检 杜 访问 记录 ， 如 果 上 次 访问 
的 时 间距 当前 已 经 超出 了 允许 闪 值 ， 则 可 以 删除 访问 记录 从 而 释放 共 译 内 存 。 代 码 如 下 : 





static void 


ngx http testslab expire(ngx http request t *r,ngx http testslab conf t *conf) { 


ngx time t *tp; 
ngx msec t now; 
ngx queue 七 Sy 
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ngx_ rbtree node t *node; 


ngx http testslab node 七 *]r; 


// 取出 缓存 的 当前 时 间 


tp = ngx timeofday(); 


now = (ngx msec t) (tp->sec * 1000 + tp->msec); // 循环 的 结束 条 件 为 ， 要 么 链表 空 了 ， 要 么 遇 到 了 一 个 不 需要 淘汰 的 结 点 


// 要 先 判断 链表 是 否 为 空 


if (ngx queue empty (&conf->sh->cueue)) { 


// 链表 为 空 则 结束 循环 


return; 


// 从 链表 尾部 开始 淘汰 


// 因为 最 新 访问 的 记录 会 更 新 到 链表 首部 ， 所 以 尾部 是 最 老 的 记录 





口 由 掉 由 有 有 和 所 掉 由 http' /wNv inuxorobe. con 





q = ngx queue last (&conf->sh->queue); // ngx queue data 可 以 取出 


ngx_queue 成 员 所 在 结构 体 的 首 地 址 


lr = ngx queue datal(lgq, ngx http testslab node t, queue); // 可 以 从 


lr 地 址 向 前 找到 


ngx rbtree node t 


node = (ngx rbtree node t *) 
((u char *) lr - offsetof(ngx rbtree node t，data)); // 取 当 前 时 间 与 上 次 成 功 访问 的 时 间 之 差 
ms = (ngx msec int t) (now - lr->last); if (ms < conf->interval) { 


// 若 当 前 结 点 没有 淘汰 掉 ， 则 后 续 结 点 也 不 需要 淘汰 


return; 


// 将 淘汰 结 点 移出 双向 链表 
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ngx queue remove (q); 


// 将 淘汰 结 点 移出 红 黑 树 


ngx rbtree delete(&conf->sh->rbtree, node); // 此 时 再 释放 这 块 共享 内 存 


ngx slab free locked(conf->shpool, node); } 





准备 工作 环绕 ， 接 下 来 可 以 开始 定义 http 过 滤 模 块 了 。 


16.2.3 ”解析 配置 文件 


首先 定义 ngx _ command t 结 构 体 处 理 nginx.conf 配 置 文件 ， 并 在 其 后 接 2 个 参数 的 test_slab 
配置 项 ， 它 仅 能 存放 在 http 仓 块 中 ， 代 码 如 下 : 





static ngx command t ngx http testslab commandqs [] = { 
{ ngx string("test slab"), 


// 仅 支 持 在 


http 块 下 配置 


test slab 配 置 项 
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// 必须 携带 


2 个 参数 ， 前 者 为 两 次 成 功 访问 同一 


URL 时 的 最 小 间隔 秒 数 


// 后 者 为 共享 内 存 的 大 小 





NGX HTTP MAIN CONF|NGX CONF TAKFE2, ngx http testslab createmem, 


NULL }, 


ngx null command 





下 面 实现 解析 配置 项 的 方法 ngx http testslab_createmem。 只 有 当 发 现 test_slab 配 置 项 上 且 其 
后 跟着 的 参数 都 合法 时 ， 才 会 开启 模块 的 限 速 功能 。 代 码 如 下 : 





static char * 


ngx http testslab createmem(ngx conf t *cf, ngx command t cmd, void conf) { 
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ngx_ str t *value; 


ngx shm zone t *shm zone; // conf 参 数 为 


ngx http testslab create main conf 创 建 的 结构 体 


ngx http testslab conf t mconf = (ngx http testslab conf t )conf; // 这 块 共享 内 存 的 名 字 


ngx str t name = ngx string("test slab shm"); // 取 到 


test_slab 配 置 项 后 的 参数 数组 


Value = cf->args->elts; 


// 获取 两 次 成 功 访问 的 时 间 间 隔 ， 注 意 时 间 单 位 





mconf->interval = 1000*ngx atoi(value[1lI]j.dqata value[l].len); if (mconf->interval == NGX _ ERROR || mconf->ini 


// 约定 设置 为 


-1 就 关闭 模块 的 限 速 功能 
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mconf->interval = -1; 


return "invalid value"; 


// 获取 共享 内 存 大 小 


mconf->shmsize = ngx parse size(&value[2]) 


// 关闭 模块 的 限 速 功能 


mconf->interval = -1; 


return "invalid value"; 


// 要 求 


Nginx 准 备 分 配 共 享 内 存 


shm zone = ngx shared _ memory addl(cf, &name, 





// 关闭 模块 的 限 速 功能 


mconf->interval = -1; 





if (mconf->shmsize == (ssize t) NGX ERROR || 


mconf->shmsize, 


&ngx http testslab module); 


mconf->shmsize == 


if 


(shm zone == NULI 


TinNNNnNnnn http://wWwWw linuxorobe.con 





return NGX CONF ERROR; 





// 设置 共享 内 存 分 配 成 功 后 的 回调 方法 


shm zone->init = ngx http testslab shm init; // 设置 


init 回 调 时 可 以 由 


data 中 获取 


ngx_http testslab conf t 配 置 结构 体 


shm zone->data = mconf; 


return NGX CONF OK; 





全 局 ngx http_testslab_conf t 配 置 结构 体 的 生成 由 ngx http_testslab_create main conf 方 法 负 
贡 ， 它 会 设置 到 ngx http module t 中 。 其 代码 如 下 : 





static void * 


ngx http testslab create main conf (ngx conf 七 xcf) { 
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ngx http testslab conf 七 *conf; 


// 在 


worker 内 存 中 分 配 配置 结构 体 


conf = ngx pcalloc (cf->pool, sizeof (ngx http testslab conf t+)); if (conf == NULL) { 


return NULL; 


// interval 初 始 化 为 


-1 ， 同 时 用 于 判断 是 否 未 开局 模块 的 限 速 功能 


conf->interval = -1; 


conf->shmsize = -1; 


return conf; 





ngx_shared_ memory_add 执 行 成 功 后 ，Nginx 将 会 在 所 有 配置 文件 解析 完毕 后 开始 分 配 共 
享 内 存 ， 并 在 名 为 test_slab_shm 的 slab 共 享 内 存 初 始 化 完毕 后 回调 ngx_http_testslab_shm init 方 
法 ， 该 方法 实现 如 下 : 
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ngx http testslab shm init(ngx shm zone t *shm zone void *data) { 





ngx http testslab conf 七 *conf; 


// data 可 能 为 空 ， 也 可 能 是 上 次 
ngx http testslab shm init 执行 完成 后 的 


shm zone->data 
ngx http testslab conf t *oconf = data; size t len; 


// shm zone->qdata 存 放 着 本 次 初始 化 


cycle 时 创建 的 


ngx http _ testslab conf tt 配置 结构 体 


conf = (ngx http testslab conf t *)shm zone->data; // 判断 是 否 为 


reload 配 置 项 后 导致 的 初始 化 共享 内 存 


if (OGOnf) 4 


// 本 次 初始 化 的 共享 内 存 不 是 新 创建 的 
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// 此 时 ， 


data 成 员 里 就 是 上 次 创建 的 


ngx http testslab conf t 


// 将 


sh 和 


shpool 指 针 指 向 旧 的 共享 内 存 即 可 


conf->sh = oconf->sh; 


conf->shpool = oconf->shpool; return NGX OK; 


// shm.addr 里 放 着 共享 内 存 首 地 址 


:ngx_slab pool 七 结 构 体 


Conf->shpool = (ngx slab pool 上 *) shm zone->shm.addr; // slab 共 享 内 存 中 每 一 次 分 配 的 内 存 都 用 于 存放 
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conf->sh = ngx slab alloc(conf->shpool，sizeof (ngx http testslab shm t)); if (conf->sh == NULL) { 


return NGX ERROR; 





conf->shpool->data = conf->sh; // 初始 化 红 黑 树 


ngx rbtree init(&conf->sh->rbtree, &conf->sh->sentinel, ngx http testslab rbtree insert value); // 初始 化 按 访 





ngx queue init(&conf->sh->queue); // slab 操 作 共 享 内 存 出 现 错误 时 ， 其 


log 输 出 会 将 


log_ctx 字 符 串 作为 后 级 ， 以 方便 识别 


len = sizeof(" in testslab \"\"") + shm zone->shm.name.len; conf->shpool->log ctx = ngx slab alloc (conf->shr 


return NGX ERROR; 





ngx sprintf (conf->shpool->log ctx, " in testslab \"%$V\"%2Z", &shm zone->shm.name); return NGX OK; 
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16.2.4 定义 模块 


先 定义 http 模 块 的 回调 接口 ngx http testslab module ctxk， 设 置 main 级 别 配置 结构 体 的 生 
成 方法 为 ngx_ http testslab create main conf( 因 为 是 main 级 别 ， 所 以 不 需要 实现 其 merge 合 3 
配置 项 方法 ) ， 再 设置 http 配 置 项 解析 完毕 后 的 回调 方法 ngx_http_testslab_init， 用 于 在 11 个 
http 请 求 处 理 阶段 中 选择 一 个 处 理 请 求 ， 如 下 所 示 : 





static ngx http module t ngx http testslab module ctx = 





NULL, /* preconfiguration */ 


ngx http testslab init, /* postconfiguration */ 


ngx http testslab create main conf, /* create main configuration */ 

















NULL, /* init main configuration */ 

NULL, /* create server configuration */ 
NULL, /* merge server configuration */ 
NULL, /* create location configuration */ 
NULL /* merge location configuration */ 














ngx_http_testslab_init 方 法 用 于 设置 本 模块 在 NGX_HTTP_PREACCESS_PHASE 阶 段 生 
效 ， 代 码 如 下 : 





static ngx int t 
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ngx http testslab init (ngx conf 七 xcf) 


ngx http handler pt 一 


ngx http core main conf 七 *cmcf; 





cmcf = ngx http conf get module main conf (cf, ngx http core module); // 设置 模块 在 








NGX_HTTP PREACCESS_PHASE 阶 段 介 入 请 求 的 处 理 

















h = ngx array push(&cmcf->phases[NGX HTTP PREACCESS PHASE] .handlers); if (hn == NULL) ({ 

















return NGX ERROR; 


// 设置 请 求 的 处 理 方法 


*h = ngx http testslab handler; 


return NGX OK; 





这 里 请 求 的 处 理 方法 被 设置 为 ngx http testslab handler 了 ， 因 为 在 15.2.2 节 中 己 经 准备 好 
了 ngx_http_testslab_lookup 方 法 ， 所 以 它 的 实现 就 变 得 很 简单 ， 如 下 所 示 : 











static ngx int t 
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ngx http testslab handler (ngx http request t *r) { 


size 七 len; 
uint32 七 hash; 
ngx int t rc; 

ngx http testslab conf t *conf; 











conf = ngx http get module main conf(r, ngx http testslab module); rc = NGX DECLINED; 








// 如 果 没 有 配置 


test slab, 或 者 


test slab 参 数 错误 ， 返 回 





NGX_DECLINED 继 续 执行 下 一 个 











http handler 
if (conf->interval == -1) 
PEtuUrnNn TC» 


// 以 客户 端 


IP 地 址 ( 


PPT FF 人 作 丫 PhttpD' // Ww inuxprobe. con 





// 和 


url 来 识别 同一 请 求 


len = r->connection->addr text.len + r->uri.len; u char* data = ngx palloc(r->pool, len); ngx memcpy (data, : 


crc32 算 法 将 


IP+URL 字 符 串 生成 


hash 码 


// hash 码 作为 红 黑 树 的 关键 字 来 提高 效率 


hash = ngx crc32 short (data, len); 


// 多 进程 同时 操作 同一 共享 内 存 ， 需 要 加 锁 
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ngx shmtx lock(&conf->shpool->mutex); rc = ngx http testslab lookupl(r, conf, hash, data, len); ngx shmtx un 





最 后 ， 定 义 ngx_http_testslab_module 模 块 : 





ngx module t ngx http testslab module = 








NGX MODULE V1, 


&ngx http testslab module ctx, /* module context */ 


ngx http testslab commands, /* module directives */ 


NGX HTTP MODUL 





加 


~ 


/* module type */ 


NULL, /* init master */ 
NULL, /* init module */ 
NULL, /* init process */ 
NULL, /* init thread */ 
NULL, /* exit thread */ 
NULL, /* exit process */ 
NULL, /* exit master */ 


NGX MODULE V1 PADDING 





过 








这 样 ， 一 个 文 持 多 进程 间 共 吝 数 据 、 共 同 限制 用 户 请 求 访问 速度 的 模块 就 完成 了 。 
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16.3 slab 内 存 管 理 的 实现 原理 





怎样 动态 地 管理 内 存 呢 ? 先 看 看 需要 面 对 的 两 个 主要 问题 : 
. 在 时 间 上 ， 使 用 者 会 随机 地 申请 分 配 、 释 放 内 存 ; 


` 在 空间 上 ， 每 次 申请 分 配 的 内 存 大 小 也 是 随机 的 。 





这 两 个 问题 将 给 内 存 分 配 算 法 带 来 很 大 的 挑战 ， 当 多 次 分 配 、 释 放 不 同 大 小 的 内 存 后 ， 
将 不 可 避免 地 造成 内 存 人 寿 片 ， 而 内 存 人 雄 片 会 造成 内 存 浪费 、 执 行 速度 变 慢 ! 常见 的 算法 有 2 
个 设计 方 回 : firstfit 和 bestfit。 用 最 简单 的 实现 方式 来 描述 这 2 个 算法 就 是 : 知已 使 用 的 内 存 
之 间 有 许多 不 等 长 的 空间 内 存 ， 那 么 分 配 内 存 时 ，first-fit 将 从 头 亿 历 空 用 内 存 块 构成 的 链 
表 ， 当 找到 的 第 1 块 空间 大 于 请 求 size 的 内 存 块 时 ， 束 把 它 返 回 给 申请 者 ;best-fit 则 不 然 ， 它 
也 会 扣 历 空 几 链表 ， 但 如 果 一 块 空间 内 存 的 空间 远大 于 请 求 size， 为 了 避免 浪费 ， 它 会 继续 
回 后 过 历 ， 看 看 有 没有 恰好 适合 申请 大 小 的 空间 内 存 块 ， 这 个 算法 将 试图 返回 最 适合 例如 
内 存 块 大 小 等 于 或 者 略 大 于 申请 size) 的 内 存 块 。 这 样 ，firstfit 和 bestfit 的 优 劣 仿佛 已 一 目 了 
然 : 前 者 分 配 的 速度 更 快 ， 但 内 存 浪费 得 多 ; 后 者 的 分 配 速度 慢 一 些 ， 内 存 利 用 率 上 却 更 划 
算 。 而 且 ， 前 者 造成 内 存 雁 片 的 几率 似乎 要 大 于 后 者 。 




















Nginx 的 slab 内 存 分 配方 式 是 基于 best-fit 思 路 的 ， 即 当 我 们 申请 一 块 内 存 时 ， 它 只 会 返回 
恰好 符合 请 求 大 小 的 内 存 块 。 但 是 ， 怎 样 可 以 更 快速 地 找到 best-fit 内 存 块 呢 ? Nginx 首 先 有 一 
个 假定 : 所 有 需要 使 用 slab 内 存 的 模块 请 求 分 配 的 内 存 都 是 比较 小 的 〈 绝 大 部 分 小 于 

) 。 有 了 这 个 假定 ， 就 有 了 一 种 快速 找到 最 合适 内 存 块 的 方法 ， 主 要 包括 5 个 要 点 : 











1) 把 整 块 内 存 按 4KB 分 为 许多 页 ， 这 样 ， 如 果 每 一 页 只 存放 一 种 固定 大 小 的 内 存 块 ， 
由 于 一 页 上 能 够 分 配 的 内 存 块 数量 是 很 有 限 的 ， 所 以 可 以 在 页 首 上 用 bitmap 方 式 ， 按 二 进 制 
位 表示 页 上 对 应 位 置 的 内 存 块 是 否 在 使 用 中 。 只 是 遍历 bitmap 二 进 制 位 去 寻找 页 上 的 空闲 内 
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存 块 ， 使 得 消耗 的 时 间 很 有 限 ， 例 如 bitmap 占用 的 内 存 空间 小 导致 CPU 缓存 命中 率 高 ， 可 以 
按 32 或 64 位 这 样 的 总 线 长 度 去 寻找 空闲 位 以 减少 访问 次 数 等 。 
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所 有 空闲 页 构成 链表 











ngx_slab_page_t 
ngx_slab_page_t 


空闲 页 
链表 


ngx_slab_page_t 


ngx_slab_page_t 
于 





于 相应 slot 下 \_ 


ngx_slab_page_t 


ngx_slab_page 





链表 












允许 1 个 超大 
块 使 用 1 个 或 
者 多 个 页 面 


ngx_slab_page_t 





ngx_slab_page_t 


加 本 加 到 本 四 加 本 而 加 画 本 本 [可 司 | nuxpr obe. con 





图 16-2 slab 内存 示 意图 








2) 基于 空间 换 时 间 的 思想 ，slab 内 存 分 配器 会 把 请 求 分 配 的 内 存 大 小 简化 为 极为 有 限 的 
几 种 〈 简 化 的 方法 有 很 多 ， 例 如 可 以 按照 fbonacci 方 法 进行 ) ， 而 Nginx slab 是 按 2 的 倍数 ， 
将 内 存 块 分 为 %、16、32、64.…… 字 节 ， 当 申请 的 字 节 数 大 于 8 小 于 等 于 16 时 ， 就 会 使 用 16 字 
节 的 内 存 块 ， 以 此 类 推 。 所 以 ， 一 种 页 面 知 存放 的 内 存 块 大 小 为 N 字 节 ， 那 么 ， 使 用 者 申请 
的 内 存在 N/2+1 与 N 之 间 时 ， 都 将 使 用 这 种 页 面 。 这 样 最 多 会 造成 一 倍 内 存 的 浪费 ， 但 使 得 
页 种 类 大 大 减少 了 ， 这 会 降低 雁 片 的 产生 ， 提 高 内 存 的 利用 率 。 


























3) 让 有 限 的 几 种 页 面 构成 链表 ， 且 各 链表 按 序 保存 在 数组 中 ， 这 样 一 来 ， 用 直接 寻 址 
法 就 可 以 快速 找到 。 在 Nginx slab 中 ， 用 slots 数 组 来 存放 链表 首页 。 例 如 ， 如 有 打 申 请 的 内 存 大 
小 为 30 字 市 ， 那 么 根据 最 小 的 内 存 块 为 8 字 节 ， 可 以 算出 从 小 到 大 第 3 种 内 存 块 存放 的 内 存 大 
小 为 32 字 节 ， 符 合 要求 ， 从 slots 数 组 中 取 第 3 个 元 素 则 可 以 寻找 到 32 字 贡 的 页 面 。 





4) 这 些 页 面 中 分 为 空 亲 页 、 半 满 页 、 全 满 页 。 为 什么 要 这 么 划分 呢 ? 因为 上 述 的 同 种 
页 面 链 表 不 应 当 包 合 太 多 元 素 ， 否 则 分 配 内 存 时 过 历 链 表 一 样 非常 耗 时 。 所 以 ， 全 满 页 应 当 
脱离 链表 ， 分 配 内 存 时 不 应 当 再 访问 到 它 。 空 用 页 应 该 是 超然 的 ， 如 果 这 个 页 面 曾经 为 32 字 
节 的 内 存 块 服务 ， 在 它 又 成 为 空 页 时 ， 下 次 便 可 以 为 128 字 市 的 内 存 块 服务 。 因 此 ， 所 有 
的 空闲 页 会 单独 构成 一 个 空闲 页 链表 。 这 里 slots 数 组 采用 散 列表 的 思想 ， 用 快速 的 直接 寻 址 
方式 将 半 满 页 展现 在 使 用 者 面前 。 








5) 虽然 大 部 分 情况 下 申请 分 配 的 内 存 块 是 小 于 4KB 的 ， 但 极 个 别 可 能 会 有 一 些 大 于 
4KB 的 内 存 分 配 请 求 ， 拒 绝 它 则 太 粗 肾 了 。 对 于 此 ， 可 以 用 遍历 空闲 页 链表 寻找 地 址 连续 的 
空闲 页 来 分 配 ， 例 如 需要 分 配 11KB 的 内 存 时 ， 则 遇 历 到 3 个 地 址 连续 的 空 亲 页 即 可 。 


以 上 $ 点 ， 就 是 Nginx slab 内 存 管理 方法 的 主要 思想 ， 如 图 16-2 所 示 。 


图 16-2 中 ， 每 一 页 都 会 有 一 个 ngx slab page t 结 构 体 描述 ，object 是 申请 分 配 到 的 内 存 存 
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放 的 对 象 ， 阴 影 方 其 是 已 经 分 配 出 的 内 存 块 ， 空 白 方 块 则 是 未 分 配 的 内 存 块 。 下 面 开 始 详细 
描述 slab 算 法 。 


16.3.1 ”内存 结构 布局 


每 一 个 slab 内 存 池 对 应 着 一 块 共享 内 存 ， 这 是 一 段 线 性 的 连续 的 地 址 空间 ， 这 里 不 只 是 
有 将 要 分 配给 使 用 者 的 应 用 内 存 ， 还 包括 slab 管 理 结 构 ， 事 实 上 从 这 块 内 存 的 首 地 址 开始 就 
是 管理 结构 体 ngx slab pool t， 我 们 看 看 它 的 定义 : 











typedef struct { 


// 为 下 面 的 互 斥 锁 成 员 


ngx shmtx 七 mutex 服 务 ， 使 用 信号 量 作 进程 同步 工具 时 会 用 到 它 


ngx shmtx sh 七 lock; 


// 设 定 的 最 小 内 存 块 长 度 


size 七 min size; 


// min size 对 应 的 位 偏 移 ， 因 为 





Slab 的 算法 大 量 采 用 位 操作 ， 从 下 面 章节 里 可 以 看 出 先 计算 出 
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// min _ shift 很 有 好 处 


SS- 七 min shift; 


/7/- 答 三 页 对 详 三 木 


ngx_slab page 鞋 页 描述 结构 体 ， 所 有 的 


ngx Slab page 七 存放 在 连续 的 


// 内 存 中 构成 数组 ， 而 


pages 就 是 数组 首 地 址 


ngx slab page t *pages; 


// 所 有 的 空 闪 页 组 成 一 个 链表 挂 在 


free 成 员 上 


ngx slab page t free; 


| 


A 人 实际 页 面 [让 


[| 门口 


入 
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1 页 的 首 地 址 就 是 


start 
u Char 帮 久 七喜 基 七 2 


// 指向 这 段 共享 内 存 的 尾部 


u char *end; 


Nginx 封 装 的 互 斥 锁 ， 这 里 就 是 一 个 应 用 范例 


ngx_ShmtX 七 mutex; 


// slab 操 作 和 失败 时 会 记录 日 志 ， 为 区 别 是 哪个 


slab 共 享 内 存 出 错 ， 可 以 在 


slab 中 分 配 一 段 内 存 存 
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// 放 描 述 的 字符 串 ， 然 后 再 用 


Tog_ctx 指 向 这 个 字符 惠 


u char *1log ctx; 


// 实际 就 是 


'\0'， 它 为 上 面 的 


log_ ctx 服务 ， 当 


log_ctx 没 有 赋值 时 ， 将 直接 指向 


zero, 


// 表示 空 字符 串 防 止 出 错 


u char zero; 


// 由 各 个 使 用 
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slab 的 模块 自由 使 用 ， 


slab 管 理 内 存 时 不 会 用 到 它 


void *data; 


// 指向 所 属 的 


ngx shm zone 七 里 的 


ngx _shm 苇 成 员 的 


addr 成 员 ， 在 


16.3.3 节 再 详 述 


void *addr; 


} ngx slab pool t; 





从 图 16-3 中 可 以 看 到 ， 这 段 共 享 内 存 由 前 至 后 分 为 6 个 部 分 ， 
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ngx_slab_pool_t 结 构 体 。 


不 同 种 类 页 面 的 半 满 页 链表 构成 的 数组 ， 下 文 称 为 slots 数 组 ， 便 于 大 家 对 上 照 Nginx 源 


码 。 将 共享 内 存 首 地 址 加 上 sizeof(ngx_slab_pool bb 即 可 得 到 Slots 数 组 。 


. 所 有 页 描述 ngx_slab_page_t 构 成 的 数组 ，ngx_slab_pool_t 中 的 pages 成 员 指 向 这 个 数组 ， 


下 文 简称 为 pages 数 组 。 
` 为 了 让 地 址 对 齐 、 方 便 对 地 址 进行 位 操作 而 “牺牲 的 ”不 予 使 用 的 内 存 。 


" 真实 的 页 ， 页 中 的 地 址 需要 对 齐 以 便 进行 位 操作 ， 因 此 其 前 后 会 有 内 存 浪费 。 


ngx_slab_pool_t 中 的 start 成 员 指 向 它 。 
. 为 了 地 址 对 齐 牺 牲 的 内 存 。 


图 16-3 中 一 个 slab 共 享 内 存 与 ngx_shm zone _t 和 ngx_cycle t 的 关系 将 在 16.3.5 节 中 详 述 。 下 
面 来 看 看 slots 数 组 与 pages 数 组 是 如 何 工 作 的 。 
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ngx_slab_pool_t 
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图 16-3 ”一 个 slab 共 享 内 存 池 中 的 内 存 布局 


无 论 是 slots 数 组 还 是 pages 数 组 ， 都 是 以 页 为 单位 进行 的 ， 页 在 slab 管 理 设计 中 是 很 核心 
的 概念 。 每 一 页 都 有 一 个 描述 结构 ngx slab page t 对 应 ， 下 面 来 看 看 ngx slab page t 的 定义 
是 怎样 的 。 








typedef struct ngx slab page s ngx slab page t; struct ngx slab page s { 


// 多 用 途 


uintptr t slab; 


// 指向 双向 链表 中 的 下 一 页 


ngx slab page t *next; 


// 多 用 途 ， 同 时 用 于 指向 双向 链表 中 的 上 一 页 


uintptr t prev; 





从 图 16-2 中 可 以 看 到 ， 页 分 为 空 亲 页 和 已 使 用 页 ， 而 已 使 用 页 中 又 分 为 还 有 空 朵 空间 可 
供 分 配 的 半 满 页 和 完全 分 配 完毕 的 全 满 页 。 每 一 页 的 大 小 由 ngx pagesize 变 量 指定 ， 同 时 为 
方便 大 量 的 位 操作 ， 还 定义 了 页 大 小 对 应 的 位 移 变量 ngx pagesize shiff， 如 下 : 
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ngx uint t ngx pagesize shift; 








这 两 个 变量 可 在 ngx_os_init 方 法 中 初始 化 ， 如 下 : 





ngx int t ngx os init(ngx log t *log) { 








ngx pagesize = getpagesize(); 


for (n = ngx pagesize; n >>= 1; ngx pagesize shift++) { /* void */ } 





全 满 页 和 空闲 页 较为 简单 。 全 满 页 不 在 任何 链表 中 ， 它 对 应 的 ngx_slab_page_t 中 的 next 
和 prev 成 员 没 有 任何 链表 功能 。 





所 有 的 空 闪 页 构成 1 个 双向 链表 ，ngx_slab_pool t 中 的 free 指 向 这 个 链表 。 然 而 需要 注意 
的 是 ， 并 不 是 每 一 个 空闲 页 都 是 该 双向 链表 中 的 元 素 ， 可 能 存在 多 个 相 邻 的 页 面 中 ， 仅 首页 
面 在 链表 中 的 情况 ， 故 而 首页 面 的 slab 成 员 大 于 1 时 则 表示 其 后 有 相 邻 的 页 面 ， 这 些 相 邻 的 多 
个 页 面 作为 一 个 链表 元 素 存 在 。 但 是 ， 也 并 不 是 相 邻 的 页 面 一 定 作 为 一 个 链表 元 素 存 在 ， 如 
图 16-4 所 示 。 


























在 图 16-4 中 ， 有 5 个 连续 的 页 面 ， 左 边 是 描述 页 面 的 ngx_slab_page tt 结构 体 ， 右 边 则 是 真 
正 的 页 面 ， 它 们 是 一 一 对 应 的 。 其 中 ， 第 1、2、4、5 页 面 都 是 空闲 页 ， 第 3 页 则 是 全 满 页 。 
而 free 链表 的 第 1 个 元 素 是 第 $ 页 ， 第 2 个 元 素 是 第 4 页 ， 可 见 ， 虽 然 第 4、5 页 是 连续 的 ， 但 

， 由 于 分 配 页 面 与 回收 页 面 时 的 时 序 不 同 ， 导 致 这 第 4、5 个 页 面 间 出 现 了 相 见 不 相识 的 现 


是 
象 ， 只 能 作为 2 个 链表 元 素 存 在 ， 这 将 会 造成 未 来 分 配 不 出 占用 2 个 页 面 的 大 块 内 存 ， 虽 然 原 
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本 是 可 以 分 配 出 的 。 第 3 个 元 素 是 第 1 页 。 第 2 页 附 在 第 1 页 上 ， 这 还 是 与 分 配 、 回 收 页 面 的 时 
机 有 有关， 事实 上 ， 当 slab 内 存 池 刚刚 初始 化 完毕 时 ，free 链 表 中 只 有 1 个 元 系 ， 就 是 第 1 个 页 
面 ， 该 页 面 的 slab 成 员 值 为 总 页 数 。 第 3 页 是 全 满 页 ， 其 next 指 针 是 为 NULL， 而 prev 也 没有 指 
针 的 含义 。 
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ngx_slab_pool_t 
的 free 成 员 


该 页 面 是 相 邻 
页 ， 它 的 成 员 
没有 意义 ， 由 
前 面 页 面 的 slab 
表明 其 意义 


全 满 页 脱离 于 
任何 链表 ， 其 
next 和 prev 成 
员 没有 链接 的 
功能 


这 两 个 页 面 虽 
然 相 邻 ， 但 它 
们 之 间 并 不 知 
道 ， 所 以 ,各 
自 独立 的 存在 
于 链表 中 








图 16-4 空闲 页 与 全 满 页 的 ngx_slab_page t 成 员 意义 





对 于 半 满 页 ， 存 放 相同 大 小 内 存 块 的 页 面 会 构成 双向 链表 ， 挂 在 slots 数 组 的 相应 位 置 
上 ， 图 16-2 中 已 经 可 以 看 到 。 那 么 ， 页 面 上 究竟 会 分 出 多 少 种 不 同 大 小 的 内 存 块 呢 ? 


ngx_slab_pool t 中 的 min_size 成 员 已 经 指定 了 最 小 内 存 块 的 大 小 ， 它 在 初始 化 slab 的 方法 
nex slab init 中 赋值 : 





void ngx Slab init(ngx slab pool 七 *pool) { 


pool->min size = 1 << pool->min shift; ... 





而 min_shift 同 样 是 为 了 位 操作 而 设 的 ， 它 的 初始 化 则 是 将 在 16.3.3 市 介绍 的 
ngx init zone pool 方 法 里 赋值 的 : 





static ngx int t 


ngx init zone pool (ngx cycle t cycle, ngx shm zone t zn) { 


ngx slab pool t *sp; 


sp->min shift = 3; 
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页 面 能 够 存放 的 最 大 内 存 块 大 小 则 由 变量 ngx_slab_max size 指定 : 





// 存放 多 个 内 存 块 的 页 面 中 ， 人 允许 的 最 大 内 存 块 大 小 为 


ngx slab max size 


static ngx uint t ngx slab max size; 








它 的 大 小 实际 是 页 面 大 小 的 一 半 【 在 ngx_slab_init 方 法 中 设置 ): 





if (ngx Slab max size == 0) { 


ngx slab max size = ngx pagesize / 2; 





为 什么 是 ngx pagesize/2 而 不 干脆 就 是 ngx pagesize 呢 ?反正 一 个 页 面 只 存放 一 个 内 存 块 
也 可 以 啊 ! 这 是 因为 slab 中 把 不 等 长 的 内 存 大 小 分 为 了 4 个 大 类 ， 这 样 分 类 后 ， 可 以 使 得 
ngx_slab_page_t 的 3 个 成 员 与 实际 页 面 的 内 存 管理 在 时 间 和 空间 上 更 有 效率 。 这 4 大 类 的 定义 
还 需要 1 个 变量 ngx slab exact size 的 参与 ， 如 下 : 








static ngx uint 七 ngx slab exact size; static ngx uint 七 ngx slab exact shift; 











它 的 赋值 也 在 ngx slab init 方 法 中 进行 : 





ngx slab exact size = ngx pagesize / (8 * sizeof (uintptr t)); for (n = ngx slab exact size; n >>= 1; ngx slab e: 


J "FOL Y/ 
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ngx_slab_exact_size 到 底 想 表达 什么 意思 呢 ? 


其 实 就 是 ，ngx_slab_page t 的 slab 中 是 否 可 以 恰好 以 bitmap 的 方式 指明 页 面 中 所 有 内 存 块 
的 使 用 状态 。 例 如 ，1 个 二 进 制 位 就 可 以 用 0 和 1 表示 内 存 块 是 否 被 使 用 ，slab 成 员 的 类 型 是 
uintptr _ t， 它 有 sizeoftuintptr 问 个 字 节 ， 每 个 字 节 有 8 位 ， 这 样 按 顺序 slab 就 可 以 表示 
8*sizeoftuintptr 个 内 存 块 。 如 果 1 个 页 面 中 正好 可 以 存放 这 么 多 内 存 块 ， 那 么 slab 就 可 以 只 
当做 bitmap 使 用 ， 此 时 ， 该 页 面 存 放 的 内 存 块 大 小 就 是 ngx_pagesize/(8*sizeof(uintptr D)。 以 
此 作为 标准 划分 ， 就 可 以 更 精确 地 使 用 slab 成 员 了 。 表 16-1 就 展示 了 4 类 内 存 是 怎样 划分 的 ， 
以 及 ngx slab page t 各 成 员 的 意义 。 




















表 16-1 4 类 内 存 中 页 面 描 述 ngx_slab_page_t 的 各 成 员 意 义 


ngx_slab_page + 


表示 该 页 面 上 存放 的 等 长 内 存 块 | 指向 双向 链表 的 下 | 低 2 位 为 11， 以 NGX_ 
大 小 ， 当 然 是 用 位 但 移 的 方式 存放 | 一 个 元 素 ， 如 果 不 在 |SLAB SMALL 表示 当前 页 
的 双 问 链表 p， 则 为 0 | 面 存放 的 是 小 块 内 存 

低 2 位 为 10， 以 NGX 
SLAB EXACT 表 示 当 前 页 
面 存 放 的 是 中 等 大 小 的 内 存 





小 块 内 存 ， 小 于 ngx_ 


slab exact size 


中 等 内 存 ， 等 于 ngx_| 作为 bitmap 表示 页 上 的 内 存 块 是 
slab_exact size 舍 已 被 使 用 


疝 工 DC STORAGE MAP 
大 块 内 存 ， 大 于 ngx_ ee 
| MASK 位 表示 bitmnap， 而 低 ITDC 
slab exact size 而 小 于 a 
STORAGE SHIFT MASK 位 表示 存 放 的 是 大 块 内 存 
J 是 块 办 人 和 仔 
放 的 内 存 块 大 小 


低 2 位 为 01， 以 NGX_ 
SLAB_BIG 表示 当前 页 面 存 
ngx slab max size 


超大 内 存 会 使 用 1 页 或 者 多 页 ， 
这 些 页 都 在 一 起 使 用 。 对 于 这 批 页 


, … 一 | 面 中 的 第 1 页 ，slab 的 前 3 位 会 被 低 2 位 为 00， 以 NGX_ 
超 大 内 存 ， 大 于 证 于 Ni » , = en 一 一- 
设 为 NGX_SLAB PAGE START， SLAB PAGE 表示 当前 页 面 
其 余 位 表示 紧 随 其 后 相 邻 的 同 批 页 是 以 整 页 来 使 用 

面 数 ; 反之 ，slab 会 被 设 为 NGX 

SLAB PAGE BUSY 


nex slab max size 


16.3.2 ”分配 内 存 流程 
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分 配 内 存 时 ， 主 要 涉及 在 半 满 面 上 分 配 和 从 空闲 页 上 分 配 新 页 ， 并 初始 化 这 2 个 流程 ， 
而 半 满 页 分 配 又 涉及 在 bitmap 上 查找 空闲 块 ， 对 于 小 块 、 中 等 、 大 块 内 存 这 三 种 页 面 而 言 ， 
其 bitmap 放 置 的 位 置 并 不 相同 ， 图 16-5 主 要 说 明了 以 上 内 容 ， 下 面 详细 解释 图 中 的 15 个 步 


又 。 


1) 如 果 用 户 申 请 的 内 存 size 大 于 前 文 介绍 过 的 ngx_slab_max size 变量 ， 则 认为 需要 按 页 
面 来 分 配 内 存 ， 此 时 跳 转 到 步 桑 2， 否则 ， 由 于 一 个 页 面 可 以 存放 多 个 内 存 块 ， 因 此 需要 考 
不 bitmap， 此 时 跳 转 到 步 又 6 继续 执行 。 








2) 判断 需要 分 配 多 少 个 页 面 才能 存放 size 字 节 ， 不 足 1 页 时 按 1 页 算 。 如 下 : 





ngx uint t pages = (size >> ngx pagesize shift) + ((size % ngx pagesize) ?1 : 0) 
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1 ) 判断 需要 分 配 的 内 存 大 小 





[ 若 size 小 于 ngx_slab_max_size] + 等 于 ngx_slab_max_size] 





6 ) 算出 恰好 可 放置 size 的 内 存 块 大 小 





2 ) 根据 请 求 大 小 计算 出 需要 多 少 个 连续 页 面 


7 ) 取得 内 存 块 所 属 半 满 页 链表 slots 





3 ) 从 free 池 中 寻找 连续 的 N 个 页 面 





8 ) 遍历 半 满 页 链表 [判断 是 否 找到 ] 


[没有 半 满 页 ] 


<> 


[找到 一 个 半 满 页 ] 


前 页 面 是 全 满 页， 脱离 链表 12 ) 从 free 池 中 分 配 1 个 页 面 [没有 足够 的 空闲 页 ] 






[没有 空闲 页 ] 


有 
[分 配 到 1 个 空闲 页 ] 


G ) 回 NULL 表 示 失 败 


(| ) 根据 bitmap 判 断 当前 页 是 否 有 空 s 闲 块 










[找到 空闲 chunk] 





3 ) 设置 页 面 为 存储 某 长 度 的 页 面 


10 ) 置 空闲 内 存 块 对 应 bitmap 位 为 1 





4 ) 设置 bitmap 第 1 位 或 者 前 n 位 为 已 使 用 
[根据 bitmap 判 出 [页 面 是 否 已 满 ] [找到 空闲 页 | 


5 ) ] 属 该 页 面 插入 半 满 页 链表 的 首部 
[页 面 还 有 空闲 内 在 块 ] 





时 


[没有 空闲 内 存 块 ] 


11 ) 将 该 页 面 分 离 出 半 满 链表 


5 ) 返回 内 存 块 首 地 址 
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图 16-5 分配 slab 内 存 的 流程 





简单 ， 只 要 遍历 到 空闲 页 就 可 以 结束 ;但 如 果 要 分 配 多 页 ，free 链 表 中 的 每 个 页 描述 
ngx_slab_page t 中 的 slab 指 明了 其 后 连续 的 空闲 页 数 ， 所 以 获取 多 个 连续 页 面 时 ， 只 要 查找 
free 链 表 中 每 个 元 素 的 slab 是 否 大 于 等 于 pages 页 面 数 即 可 。 下 面 针对 分 配 页 面 的 

ngx Slab alloc _ pages 方法 进行 说 明 : 














static ngx slab Page 七 * 
ngx Slab alloc pages (ngx Slab pool t *pool, ngx uint t pages) { 


ngx Slab page t page, p; 


free 空 闲 页 链表 ， 参 见 图 
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16-4 





for (page = pool->free.next; page != &pool->free; page = page->next) { 


// 表明 连续 页 面 数 足以 容纳 


if (page->slab >= pages) { 


// 如 果 链 表 中 的 这 个 页 描述 指明 的 连续 页 面 数 大 于 要 求 的 


Pages， 只 取 所 需 即 可 ， 


// 将 剩余 的 连续 页 面 数 仍然 作为 一 个 链表 元 素 放 在 


free 池 中 


if (page->slab > pages) { 


应 
Sy 
二 
半 
EE 
己 
小 


// page[pages] 是 这 


1 个 不 被 使 用 到 的 页 ， 所 以 ， 
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// 将 由 它 的 页 描述 


ngx slab page 七 中 的 


slab 来 表明 后 续 的 连续 页 数 


page [pages] .slab = page->slab - pages; // 接 下 来 将 剩余 的 连续 空闲 页 的 第 


1 个 页 描述 


page [pages] 作 为 


// 链表 元 素 插入 到 


free 链 表 中 ， 取 代 原 先 所 属 的 


Page 页 描述 


// 将 


口 由 掉 岂 有 有 和 所 掉 由 http' /wNv inuxorobe. con 





page [pages] 的 链表 指向 当前 链表 元 素 的 前 后 元 素 








page [pages] .next = page->next; page[pages] .prev = page->prev; // 将 链表 的 上 一 个 元 素 指向 


page [pages ] 


p = (ngx slab page t *) page->prev; p->next = &page[pages]; // 将 链表 的 下 一 个 元 素 指向 





page [Pages ] 








page->next->prev = (uintptr t) &page[lpages]; } else { 


// slab 等 于 


pages 时 ， 直 接 将 


page 页 描述 移出 


free 链 表 即 可 





p= (ngx slab page t *) page->prev; p->next = page->next; 


page->next->prev = page->prev; } 





// 这 段 连续 页 面 的 首页 描述 的 
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slab 里 ， 高 


3 位 设 





NGX SLAB PAGE START 


page->slab = pages | NGX SLAB PAGE START; // 不 在 链表 中 





NULL; 


page->next 


// prev 定 义 页 类 型 : 存放 


size>=ngx slab max _ size 的 页 级 别 内 存 块 





page->prev = NGX SLAB PAGE 


if (--pages == 0) { 


// 如 果 只 分 配 了 


1 页 ， 此 时 就 可 以 返回 


Page 了 
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return page; 


// 如 果 分 配 了 连续 多 个 页 面 ， 后 续 的 页 描述 也 需要 初始 化 
for (p = page + 1; pages; pages--) 1 


// 连续 页 作为 一 个 内 在 块 一 起 分 配 出 时 ， 非 第 


slab 都 置 为 


NGX SLAB PAGE BUSY 








p->slab = NGX SLAB PAGE BUSY; p->next = NULL; 





p->prev = NGX SLAB PAGE 


~ 


p++; 


// 连续 的 各 个 页 描述 都 初始 化 完成 后 ， 返 回 页 


page 


return page; 
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// 没有 找到 符合 要 求 的 页 面 ， 返 回 


NULL 


return NULL; 


介绍 完 ngx_ slab alloc_ pages 方 法 可 知 ， 如 果 找 到 符合 要 求 的 页 面 ， 那 么 跳 到 第 $ 步 ， 返 


回 页 面 的 首 地 址 即 可 ; 没有 找到 这 样 的 页 面 ， 跳 到 第 4 步 返 回 NULL。 
4) 返回 NULL， 表 明 分 配 不 出 新 内 存 ，OutOfMemory。 


5) 返回 可 以 使 用 的 内 存 块 首 地 址 。 





6) slab 页 面 上 人 允许 存放 的 内 存 块 以 8 字 节 起 步 ， 知 字 节 数 在 ngx_slab_ max _ size 以 内 时 是 
按 2 的 倍数 递增 的 ， 那 么 这 与 第 2 步 按 页 分 配 时 是 不 同 的 ， 按 页 分 配 时 最 多 浪 宫 ngx pagesize-1 





字 节 的 内 存 ， 例 如 分 配 4097 字 市 时 必须 返回 2 个 连续 页 ;而 按 2 的 倍数 分 配 时 ， 则 最 多 会 浪费 
size-2 字 节 内 存 ， 例 如 分 配 9 字 节 时 应 返回 16 字 节 的 内 存 块 ， 浪 费 了 7 个 字 节 。 

此 时 size 小 于 ngx_slab_max_size， 因 此 要 依据 best-fit 原 则 找 一 个 恰好 能 放下 size 的 内 存 块 
大 小 。 

7) 取出 所 有 半 满 页 链表 构成 的 slots 数 组 ， 由 于 链表 是 以 内 存 块 从 小 到 大 以 2 的 整数 倍 按 
序 放 在 数组 中 的 ， 所 以 使 用 直接 寻 址 的 方式 找到 第 6 步 指示 的 内 存 块 所 属 半 满 页 链表 。 

8) 授 历 半 满 页 链表 。 如 果 没 有 找到 半 满 页 ， 则 跳 到 第 12 步 去 分 配 新 页 存放 该 内 存 块 ; 


找到 一 个 半 满 页 ， 则 继续 执行 第 9 步 。 


口 由 掉 所 有 由 和 所 掉 由 http' /wNv inuxorobe. con 





9) 根据 表 16-1 可 知 ， 当 内 存 块 小 于 ngx slab max size 时 ， 每 页 都 必须 使 用 bitmap 来 标识 
内 存 块 的 使 用 状况 。 而 依据 bitmap 的 存放 位 置 不 同 ， 又 分 为 小 块 、 中 等 、 大 块 内 存 。 此 时 ， 
需要 根据 第 6 步 算出 的 内 存 块 大 小 ， 先 找到 bitmap 的 位 置 ， 再 遍历 它 找到 第 1 个 空闲 的 内 存 
块 。 如 果 找 到 空闲 内 存 块 ， 则 继续 执行 第 10 步 ， 和 否则 ， 这 个 半 满 面 就 名 不 符 实 了 ， 它 实际 上 
就 是 一 个 全 满 页 ， 所 以 可 以 脱离 半 满 页 链表 了 ， 继 续 第 8 步 遍 历 链 表 。 








10) 首先 将 找到 的 空 帮 内 存 块 对 应 的 bitmap 位 置 为 !， 以 示 内 存 块 在 使 用 中 。 接 着， 检 
查 这 是 合 为 当前 页 的 最 后 一 个 空 几 内存 块 ， 如 果 是 ， 则 半 渗 页 变 为 全 满 页 ， 跳 到 第 11 步 执 
行 ; 否则 ， 直 接 跳 到 第 5 步 ， 返 回 这 个 内 存 块 地 址 。 


11) 将 页 面 分 离 出 半 满 页 链表 ， 再 跳 转 到 第 5 步 。 


12) 未 找到 半 满 页 ， 需 要 从 free 空 闲 页 链表 中 申请 出 新 的 一 页 ， 参 见 第 3 步 介 绍 过 的 
ngx_slab_alloc_pages 方 法 ， 如 果 未 分 配 出 新 页 ， 跳 到 第 4 步 返 回 NULL。 





13) 设置 新 页 面 存 放 的 内 存 块 长 度 为 第 6 步 指定 的 值 。 同 时 设置 它 的 页 描述 的 prev 成 员 
低位 ， 指 明 它 是 小 块 、 中 等 还 是 大 块 内 存 块 页 面 。 








14) 新 页 面 分 配 出 了 第 1 个 内 存 块 ， 对 于 中 等 、 大 块 内 存 页 来 说 ， 置 bitmap 第 1 位 为 1 即 
可 ,但 对 于 小 块 内 存 页 ， 由 于 它 的 前 几 个 内 存 块 是 用 于 bitmap 的 ， 因 此 不 能 再 次 被 使 用 ， 所 
以 对 应 的 bit 位 需要 置 为 !， 并 把 下 一 个 表明 当前 分 配 出 的 内 存 块 的 bit 位 也 置 为 1。 


15) 这 个 新 页 面 由 空 几 页 变 为 半 满 页 ， 因 此 将 页 面 插 入 半 满 页 链表 的 首部 。 


16.3.3 释放 内 存 流程 





释放 内 存 时 不 需要 遍历 链表 、bitmap， 所 以 速度 更 快 。 图 16-6 说 明了 释放 内 存 的 完整 流 
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释放 内 存 的 流程 如 图 16-6 所 示 。 


1) 首先 判断 释放 的 内 存 块 地 址 是 否 合法 ， 依 据 为 是 否 在 ngx_slab pool t 的 start、end 成 员 
指示 的 页 面 区 之 间 。 如 果 不 合法 ， 直 接 结束 释放 流程 ， 例 如 ; 








void ngx slab free locked(ngx slab pool t pool, void p) { 


if ((u char ) p < pool->start || (ua char ) p > pool->end) { 


// Pp 地 址 非法 








2) 从 待 释放 的 内 存 块 地 址 p 可 以 快速 得 到 它 所 属 的 页 描述 结构 体 ， 如 下 : 





ngx uint t n= ((u char *) p - pool->start) >> ngx pagesize shift; ngx Slab page t * page = &pool->pages[n]; 





page 变 量 就 是 页 描述 结构 体 ， 在 16.3.4 节 会 详细 介绍 类 似 地 址 位 运算 。 





3) 根据 页 描述 结构 体 的 prev 成 员 ， 得 到 该 页 面 是 用 于 小 块 、 中 等 、 大 块 的 内 存 ， 或 者 
按 页 分 配 的 内 存 。 因 为 存放 小 块 、 中 等 、 大 块 内 存 的 页 面 含有 bitmap， 这 样 的 页 面 处 理 时 要 
再 次 核实 bitmap 中 p 对 应 的 bit 位 是 否 为 1， 防 止 重复 释放 ， 此 时 跳 到 第 5$ 步 执行 ， 如 果 p 当 初 是 
按 页 分 配 的 ， 不 需要 考虑 bitmap， 释 放 起 来 更 简单 ， 继 续 执 行 第 4 步 。 











4) 由 页 描述 的 slab 成 员 可 以 获得 当前 使 用 的 内 存 究竟 占用 了 多 少 页 (参考 图 16-5 的 第 3 
步 ) ， 如 下 : 





ngx uint t pages = slab & ~NGX SLAB PAGE START 
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接着 ， 跳 到 第 11 步 调用 ngx slab free _ pages 释放 这 pages 个 页 面 。 








5) 这 个 页 面 存 放 了 多 个 内 存 块 ， 参 考 表 16-1 可 知 ， 从 页 描述 的 slab 成 员 可 以 获取 这 个 页 
面 存放 多 大 的 内 存 块 。 





6) 用 页 大 小 除 以 内 存 块 大 小 ， 可 以 得 到 需要 多 少 个 bit 位 来 存放 bitmap。 再 根据 地 址 p 与 
页 面 首 地 址 的 相对 偏 移 量 ， 计 算出 p 对 应 的 内 存 块 占用 了 bitmap 中 的 哪个 bitfy。 
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1 ) 判断 待 释放 的 地 址 是 否 在 共享 内 存 地 址 范围 内 


[ 竺 释放 地 址 合法 ] 


2 ) 根据 参数 地 址 与 共享 内 存 起 始 地 址 之 差 ， 获 得 对 应 的 页 描述 





3 ) 由 prev 成 员 的 低 2 位 中 取出 该 页 面 的 类 型 


[释放 跨 1 到 多 页 的 超大 块 内 存 ] 


4 ) 根据 slab 计 算出 待 释放 的 页 面 数 





[ 竺 释放 地 址 不 合法 ] 
5 ) 根据 页 面 类 型 由 slab 取 出 该 页 存储 内 存 块 的 大 小 


6 ) 由 参数 地 址 与 所 在 页 地 址 差 的 偏 移 计算 出 bitmap 位 


7 ) 检查 内 存 块 对 应 bitmap 位 上 是 否 为 已 使 用 





[bitmap 显 示 内 存 块 使 用 中 ， 合 法 ] 


[bitmap 显 示 内 存 块 为 空闲 ， 重 复 释 放 不 处 理 ] 


8 ) 置 该 bitmap 位 为 0， 再 检查 当前 页 是 否 是 全 满 页 





[当前 夺 是 半 满 页 ] 


9 ) 将 当前 页 加 入 半 满 页 链表 的 首位 ， 并 使 slot 指 向 它 





已 分 配 chunk 
[页 上 还 有 在 使 用 的 chunk] 


[页 上 已 经 没有 任何 chunk] 






11 ) 释放 页 面 到 free 空 闲 页 链表 池 中 L233 
ob / WA | | NUXPr obe. con 





[HP 





则 ， 


图 16-6 ”释放 slab 内 存 的 流程 





7) 检查 bitmap 中 该 内 存 块 对 应 的 bit 位 是 否 为 1。 如 果 是 1， 那 么 执行 第 8 步 继续 释放 :; 合 
可 以 认为 当前 是 在 释放 一 个 已 经 被 释放 的 内 存 ， 结 束 释 放流 程 。 


8) 将 这 个 bit 位 由 1 改 为 0， 这 样 如 果 原 先 这 是 一 个 全 满 页 ， 就 会 变 为 半 满 页 ， 执 行 第 9 


步 ， 否则 ， 直 接 执行 第 10 步 。 
9) 当前 页 面 既然 由 全 满 页 变 为 半 满 页 ， 就 必须 插入 slots 中 的 半 满 页 链表 ， 供 下 次 分 配 
内 存 时 使 用 。 





10) 检查 bitmap 中 是 否 还 有 值 为 0 的 bitf 位 ， 判 断 当前 页 是 否 变 为 空 亲 页 ， 如 果 变 成 了 空 





朵 页 ， 则 执行 第 11 步 将 它 加 入 到 free 链 表 中 。 


11) 回收 页 面 ，ngx_slab free_ pages 方 法 负责 将 这 些 页 面 插入 到 free 链 表 中 ， 我 们 看 看 它 


的 实现 是 怎样 的 : 





static void 


ngx slab free pages (ngx slab pool t pool, ngx slab page t page, ngx uint t pages) 


ngx slab page t *prev; 


// page 将 会 加 入 到 


free 链 表 中 ， 连 续 页 面 数 为 


pages， 所 以 把 
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slab 置 为 


pages 
page->slab = pages--; 


// 除了 


page 本 身 ， 检 查 其 后 是 否 还 有 页 面 


if (pages) { 


// 将 紧邻 的 页 面 描述 结构 体 所 有 成 员 置 为 
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ngx memzero(&gpage[1]，Ppages * sizeof(ngx Slab page t+)); } 


// 将 释放 的 首页 








Page 的 页 描述 插入 到 

free 链 表 的 首部 
Page->prev = (uintptr t) &pool->free; page->next = pool->free.next; 
page->next->prev = (uintptr t) page; pool->free.next = page; 








16.3.4 如 何 使 用 位 操作 


本 市 以 较为 复杂 的 小 块 内 存 页 为 例 ， 介 绍 如 何 使 用 位 操作 来 加 速 分 配 、 释 放 内 存 ， 方 便 
读者 朋友 阅读 睡 涩 的 位 操作 部 分 源 代码 。 





除了 NGX _SLAB PAGE 类 型 的 页 面 ， 每 个 页 面 都 可 以 存放 多 个 内 存 块 。 这 样 ， 每 个 页 面 
都 需要 有 一 个 bitmap 来 表示 每 一 个 内 存 块 究竟 是 被 使 用 的 还 是 空闲 的 。 然 而 ， 如 果 一 个 页 面 
存放 的 内 存 块 大 小 小 于 ngx_slab_exact_size， 那 么 一 个 uintptr_t 是 存放 不 下 bitmap 的 。 这 时 ， 将 
会 使 用 页 面 里 的 前 几 个 内 存 块 充 当 bitmap， 如 图 16-7 所 示 。 
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实际 上 图 16-7 描 述 了 一 种 在 小 块 内 存 半 满 页 上 分 配 内 存 的 场景 。 下 面 简要 地 用 源码 中 用 
到 的 各 种 位 操作 来 描述 这 一 过 程 。 
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nox_slab_pool t 


slab 
next 
slots 数 组 
指 回 半 满 页 链表 








Re | 相 上 y 介 页 管理 
结构 此 时 slab 中 表 
示 对 应 页 面 里 
chunk 块 大 小 
prev 低 2 位 表示 该 
页 存储 小 块 chunk 
start 成 员 


| 相距 n 个 页 面 
bitmap 中 每 个 二 进 制 位 表示 对 





应 的 内 存 块 是 否 被 使 用 ， 此 时 
页 数据 < ”国宝 于 从 1100.. 置 为 1110.. 
FI 分 配 到 的 内 存 地 址 


图 16-7 小 块 内 存 页 面 的 bitmap 会 直接 占用 页 面 中 的 内 存 





用 户 在 ngx_slab_alloc 方 法 中 申请 size_tsize 大 小 的 内 存 ， 而 slab 中 是 按 2 的 过 来 决定 页 面 


朋 吕 三 这 的 乓 下 和 下 移 。 [ 唱 下 各 未 从 的 "Rt 从 TFA 6 Jie oF 下 所 











ngx uint 七 shift=1; 


size 七 s; 


for (s = size - 1; s >>= 1; shift++) { /* void */ } 





这 样 ， 我 们 获得 了 位 操作 必需 的 、 恰 好 容纳 size 字 节 的 内 存 块 的 偏 移 量 shift。 除 此 以 
外 ， 还 需要 拿 到 slots 数 组 ， 这 里 放置 了 半 满 页 构成 的 链表 ， 从 共享 首 地 址 数 起 ， 加 上 
sizeof(ngx_slab_pool 0 字 节 即 可 拿 到 ， 如 下 所 示 : 





ngx_ slab Pool 七 *pool; 


ngx Slab page t slots = (ngx slab page t ) ((u char *) pool + sizeof (ngx slab pool t+)); 





slots 数 组 中 按照 内 存 块 大 小 的 顺序 〈 从 小 到 大 ) ， 依 次 存放 了 各 种 等 长 块 页 面 构成 的 半 
满 页 链表 。 选 用 哪 一 个 slots 数 组 昵 ?” 用 shift 偏 移 减 去 表达 最 小 块 的 min_ shift 成 员 即 可 : 








ngx uint t slot = shift - pool->min shift; ngx slab page 七 *page = slots[slot] .next; 





这 样 ，page 就 将 是 一 个 半 满 页 。 如 果 slots 中 没有 半 满 页 ， 那 么 page 是 NULL。 图 16-5 中 描 
述 的 场景 是 含有 半 满 页 的 ， 所 以 下 面 继续 基于 这 个 假定 进行 说 明 。 





接着 ， 我 们 发 现 用 户 希 望 分 配 的 内 存 块 大 小 是 小 于 ngx_slab_exact_size 的 ， 此 时 ， 首 先 要 
找到 bitmap 的 初始 位 置 ， 准 备 按 位 来 查找 到 空闲 块 。bitmap 其 实 就 在 页 面 的 首 地 址 上 ， 怎 样 
用 位 操作 快速 找到 页 面 呢 ? 从 图 16-5 中 可 以 看 到 ngx_slab_pool_t 的 pages 指 针 和 start 指 针 ， 它 
们 是 关键 ! 
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上 面 找到 的 page 是 半 满 页 的 ngx slab page tt 描述 结构 体 的 首 地 址 ， 用 它 减 去 pages 就 可 以 
得 到 该 页 面 在 整个 slab 中 是 第 N 个 页 面 〈 这 2 个 相 减 的 变量 都 是 ngx_slab page 人 类 型 ) 。start 
是 对 齐 后 slab 第 1 个 页 面 的 起 始 地 址 ， 所 以 ，start 加 上 N*pagesize 束 可 以 得 到 该 半 满 页 的 实际 
页 面 首 地 址 ， 如 下 所 示 : 








uintptr t p = (page - pool->pages) << ngx pagesize shift; uintptr t* bitmap = (uintptr t *) (pool->start + p); 





这 样 ，bitmap 变 量 将 指向 bitmap 的 首 地 址 ， 同 时 也 指向 第 1 个 页 面 。 对 于 小 块 内 存 来 说 ， 
1 个 wintptr 类 型 是 注定 存放 不 下 bitmap 的 。 到 了 按 位 比较 找到 空闲 块 的 时 候 了 ， 然 而 为 了 加 
快运 算 速度 ， 我 们 并 不 能 总 按照 二 进 制 位 来 循环 进行 ， 可 以 先 用 vintptr_t 类 型 快速 与 
OxfFPPFFFFFFFFFF 《下 文 的 NGX SLAB BUSY 宏 〉 比较 ， 如 果 相 等 则 说 明 没 有 空闲 块 ， 而 不 等 时 
才 有 必要 按 二 进 制 位 慢 慢 地 找 出 那个 空闲 块 。 所 以 ， 现 在 我 们 有 必要 知道 ， 多 少 个 uintptr { 
类 型 可 以 完整 地 表达 该 页 面 的 bitmap? 用 页 面 大 小 除 以 块 大 小 可 以 知道 页 面 能 存放 多 少 个 
块 ， 除 以 8 就 可 以 知道 需要 多 少 字 节 来 存放 bitmap， 再 除 以 sizeofruintptr 就 可 以 知道 需要 多 
少 个 uintptr_t 来 存放 bitmap。 实 际 上 ， 这 一 系列 操作 下 面 这 行 语句 就 可 以 做 到 : 




















ngx uint t map = (1 << (ngx pagesize shift - shift)) / (sizeof (uintptr t) * 8); 





这 里 避免 了 更 慢 的 除法 ， 这 惑 是 位 操作 的 优势 ! map 就 是 bitmap 需 要 的 总 uintptr 做 。 下 
面 我 们 看 看 怎样 在 一 个 存放 小 块 内 存 的 半 满 面 中 ， 根 据 bitmap 的 位 操作 快速 找到 空闲 块 。 





// 共 需 要 


map 个 


uintptr 七 才能 表达 完整 的 
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for (uintptr t n= 0; n < map; n++) { 


// 通过 用 


uintptr 七 与 


NGX _SLAB BUSY 比较， 快速 


pass 掉 全 满 的 


uintptr t 
if (bitmap[n] != NGX SLAB BUSY) { 
// 确认 当前 


bitmap[n] 上 有 空闲 块 ， 再 一 位 一 位 的 查找 


for (ULntptr tC Me Ly 三 07 TE Ke TF》 下 


// 这 个 位 如 果 是 


1 则 表示 内 存 块 已 被 使 用 ， 继 续 循环 遍历 
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// 既然 找到 了 空闲 位 ， 先 把 这 个 位 从 


[1 NINIDNDDHD 
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Ditmap [n] |= m; 


// 那么 ， 当 前 的 这 个 


bi 到底 对 应 着 该 页 面 的 第 几 个 内 存 块 呢 ? 从 


n 和 


i 即 可 得 到 ， 


// n*sizeof (uintptr 七 )*x8+i。 再 使 用 


<<shift 即 可 得 到 该 内 存 块 在 页 面 上 的 字 节 偏 移 量 


i = ((n sizeof(uintptr t) 8) << shift) + (i << shift); // p 就 是 那个 空闲 块 的 首 地 址 ， 用 


bitmap 加 上 字 节 偏 移 
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p= (uintptr t) bitmap + i; 


// 后 续 还 有 操作 ， 例 如 判断 如 果 页 面 由 半 满 全 满 ， 则 脱离 链表 





如 果 没 有 半 满 页 ， 则 需要 从 free 空 有 链表 中 分 配 出 1 页 ， 再 初始 化 该 页 中 的 bitmap。 我 们 
来 看 看 源码 中 是 怎样 用 位 操作 为 初始 化 bitmap 的 。 





// page 是 从 


free 空 闲 链表 中 新 分 配 出 的 页 面 ， 用 其 与 


pages 数 组 相 减 后 即 可 得 到 是 第 几 个 页 面 ， 


// 再 左 移 


ngx pagesize shift 即 表示 从 
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p = (page - pool->pages) << ngx pagesize shift; // bitmap 既 是 页 面 的 首 地 址 ， 也 是 


bitmap 的 起 始 


bitmap = (uintptr t *) (pool->start + p); 


// s 为 该 页 存放 的 块 大 小 


站 全 


// n 表 示 需 要 多 少 个 内 存 块 才能 放 得 下 整个 


bitmap 


n= (1 << (ngx pagesize shift - shift)) 8 s; if (n == 0) { 


// 因为 前 





n 个 内 存 块 已 经 用 于 


bitmap 了 ， 它 们 不 可 以 再 被 使 用 ， 所 以 置 这 些 内 存 块 对 应 的 
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bit 位 为 





// bitmap 这 里 占用 的 内 存 块 数 ， 不 可 能 连 


1 外 


uintptr 七 都 放 不 下 ， 所 以 只 需要 设置 第 


4 人 


uintptr 七 即 可 


bitmap[0] = (2 << n) - 1; 


// map 表示 需要 多 少 个 
uintptr t 上 才能 放 得 下 整个 


bitmap 
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map = (1 << (ngx pagesize shift - shift)) / (sizeof (uintptr t) * 8); for (i = 1; i < map; i++) { 


// 设置 剩余 的 


bit 位 为 
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bitmap[i] = 0; 


// 根据 前 述 


s 和 


n 的 意义 ， 可 知 


s*n 就 是 在 这 个 页 面 里 ， 第 


1 个 可 以 使 用 的 空闲 块 的 偏 移 字 节 数 。 


// 再 加 上 该 页 面 与 


start 间 的 偏 移 量 ， 


Pp 就 是 空闲 块 与 


start 间 的 偏 移 量 
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p = ((page - pool->pages) << ngx pagesize shift) + S x n; // 于 是 得 到 该 空闲 块 的 首 地 址 


p += (uintptr t) pool->start; 





而 释放 内 存 块 时 ， 位 操作 依然 可 以 大 大 加 速 执 行 时 间 。 





void ngx slab free locked(ngx slab pool t pool, void p) { 


// 内 存 块 指针 


Pp 与 


start 之 间 的 偏 移 字 节 数 ， 除 以 页 面 字 节 数 的 结果 取 整 ， 就 是 


P 所 在 的 页 面 在 所 有 


// 页 面 中 的 序号 


ngx uint t n= ((u char *) p - pool->start) >> ngx pagesize shift; // 根据 


n 就 取 到 了 
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P 所 在 页 面 的 


ngx_slab page 鞋 页 面 描述 结构 体 


ngx slab page t * page = &pool->pages [n]; // 找到 页 面 对 应 的 


slab 


uintptr t slab = page->slab; 


// slab 的 低 


NGX_SLAB PAGE MASK 位 存放 的 是 页 面 类 型 





ngx uint 七 type = page->prev & NGX SLAB PAGE MASK; ... 








拿 到 了 type 后 ， 需 要 对 4 种 页 面 区 别 对待 。 仍 然 以 小 块 内 存 举 例 : 





// 对 于 小 块 内 存 ， 


slab 的 低 
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NGX_SLAB SHIEFT MASK 位 存放 了 内 存 块 大 小 ， 


shift 变 量 取出 了 块 大 小 的 位 移 量 


shift = slab & NGX SLAB SHIFT MASK; 


// size 取 得 的 块 大 小 


size = 1 << shift,; 


// 把 内 存 块 的 首 地 址 


p 按 页 大 小 取 余数 ， 就 是 


P 相 对 于 该 页 面 首 地 址 的 偏 移 字 节 ， 再 除 以 块 大 小 ， 


// 那么 


n 就 是 该 内 存 块 在 页 面 中 的 序号 


n = ((uintptr t) p & (ngx pagesize - 1)) >> shift; // 现在 把 
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n 这 个 序号 应 用 于 


bitmap。 


bitmap 可 能 由 多 个 


uintptr 七 组 成 ， 而 


Dn 从 属于 某 一 个 


过 i 


// 先 把 


n 求 得 


uintptr t 中 的 余数 表明 这 个 内 存 块 对 应 的 


bit 位 ， 在 其 所 属 的 
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uintptr 七 里 的 序号 ， 


// 并 把 


1 左 移 这 些 位 ， 这 样 ， 


m 就 是 


P 内 存 块 


bit 位 所 在 


uintptr 七 中 的 位 


m= (uintptr t) 1 << (n & (sizeof (uintptr t) x 8 - 1)); // n 再 除 以 


uintptr 七 能 够 表达 的 


bit 位 ， 此 时 表示 
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bit 位 前 还 有 


n 个 表示 


bitmap 


// 的 


uintptr t 
n /= (sizeof (uintptr t) * 8); 


// 把 


Pp 的 相当 于 一 页 的 低位 去 挤 ， 此 时 


bitmap 就 是 该 页 面 的 首 地 址 ， 也 是 所 有 


bitmap 的 起 始 地 址 


bitmap = (uintptr t *) ((uintptr t) p & ~(ngx pagesize - 1)); // 用 


bitmap [mn] 与 
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m 相 与 ， 可 以 再 次 确认 


P 相 对 应 的 内 存 块 是 否 是 在 使 用 中 ， 如 果 没 有 在 使 用 中 ， 


ss 
ts 


就 是 两 次 释放 了 


Fi 
mh 


(bitmap[n] & m) { 


// 释放 该 内 存 块 ， 其 实 就 是 把 


bit 位 从 


1 置 为 
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Ditmap[n] &= ~m; 


// 下 面 还 要 检查 当前 页 面 没有 已 使 用 内 存 块 了 ， 如 果 是 这 样 ， 需 要 回收 该 页 








对 于 中 等 内 存 块 、 大 块 内 存 块 页 面 来 说 ， 由 于 bitmap 是 放 在 slab 成 员 中 的 ， 所 以 位 操作 
会 更 简单 ， 这 里 就 略 过 


16.3.$ _ slab 内存 池 间 的 管理 
Nginx 人 允许 多 个 模块 各 自 独立 地 定义 slab 内 存 池 ， 这 意味 着 可 以 并 存 多 个 slab 内 存 池 。 同 


时 ，Nginx 允 许 模块 A 定 义 的 内 存 池 被 模块 B 使 用 ， 这 样 内 存 池 间 必 须 被 管理 起 来 。 描 述 整 个 
Nginx 的 ngx_cycle_s 结 构 体 中 有 一 个 链表 ， 保 存 着 所 有 的 slab 内 存 池 ， 如 下 所 示 : 





struct ngx Cycle s { 


ngx list t shared memory; 








shared memory 以 链表 的 方式 保存 着 ngx_shm zone tt 结构 体 。 前 面 在 16.1 节 中 就 介绍 过 这 
个 结构 体 ， 它 对 应 着 1 个 slab 共 享 内 存 池 。ngx shm zone t 具 有 自己 的 名 字 ， 还 可 以 定义 自己 
仪 能 够 被 某 个 模块 使 用 (tag 成 员 ) 。ngx shared memory add 方 法 就 是 在 同 shared memory 链 
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历 shared memory 链表 ， 依 次 地 初始 化 每 一 个 slab 内 存 池 。 
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16.4 ”小 结 


本 章 首 先 介绍 使 用 slab 内 存 池 的 方法 ， 并 以 一 个 有 代表 性 的 例子 介绍 使 用 它 的 方法 ， 读 
者 朋友 可 以 结合 访问 本 书 网 站 上 可 以 运行 的 示例 代码 来 阅读 。 








接着 ， 我 们 开始 剖析 它 的 实现 ，slab 也 是 Linux 内 核 中 一 种 优秀 的 内 存 管理 机 制 ， 理 解 其 
设计 思想 不 只 有 助 于 开拓 思路 ， 更 可 以 改进 它 。 例 如 ，slab 内 存 池 其 实 对 于 大 于 4KB 的 内 存 
的 使 用 很 不 友好 ， 在 持续 的 分 配 释放 中 ， 连 续 痢 的 空闲 页 会 越 来 越 少 ， 尤 其 是 有 些 空 亲 页 明 
明 是 连续 的 ， 但 是 可 能 也 认为 它们 是 分 离 的 ， 就 像 图 16-4 中 的 例子 那样 。 又 比如 ， 假 定 我 们 
申请 的 内 存 基 本 都 是 在 4KB 以 上 的 ， 这 就 不 能 再 使 用 操作 系统 的 页 大 小 作为 内 存 池 的 页 大 小 
了 ， 可 以 通过 增加 页 的 大 小 以 提高 内 存 的 使 用 率 〈 注 意 : 这 可 能 导致 ngx slab page {t 页 描述 
的 slab 成 员 中 存放 的 内 存 块 大 小 位 移 超出 NGX SLAB SHIFT MASK， 需 要 综合 考虑 ) 。 











另外 ，slab 的 源码 体现 了 极为 优秀 的 编码 艺术 ， 大 量 的 位 操作 极 大 地 提高 了 效率 ， 非 常 
值得 C 程 序 员 们 认真 学 习 。 
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